Subject: [tryton] Re: Request for Comment: Client manual

From: udono <[email-masked]>
Date: Thu, 30 Oct 2008 07:54:05 -0700 (PDT)

On 29 Okt., 13:16, udono <[email-masked]> wrote:
> Thanks for quick reply!
>
> On 29 Okt., 09:52, Mathias Behrle <[email-masked]> wrote:>
> > I am dropping in once again the question, if we shouldn't use another, IMHO
> > better wiki solution than google wiki. It is a very basic and simple
> > implementation and doesn't offer for example the possibility to present a well
> > structured menu as first page. With time and growing number of pages we will
> > have a bunch of pages on first level without the possibility to hide pages,
> > that only should be linked to. I am used to work with mediawiki
> > (http://abanq-de.dyndns.org/wiki), that offers much more
> > comfort in this respect (as you know, udono, since you were wiki admin of
> > LxOffice IIRC;), but please share your experience and opinion about that...).
> > So I would favour to migrate to a better wiki solution like mediawiki before
> > having much more pages.
> Since some four years documenting LX-Office via mediawiki, I diagnose
> serveral problems with wiki for documenting growing software products.
> But give me some time to describe the problems and maybe some
> solutions. I will (re)post a concept paper tomorrow.
No complete concept paper following, but some points to consider and
discuss.
http://groups.google.com/group/tryton/t/8579ed890aedb63a

Cheers Udo
--~--~---------~--~----~------------~-------~--~----~
[email-masked] mailing list
-~----------~----~----~----~------~----~------~--~---

---

From: udono <[email-masked]>
Date: Wed, 29 Oct 2008 05:16:24 -0700 (PDT)

Thanks for quick reply!

On 29 Okt., 09:52, Mathias Behrle <[email-masked]> wrote:
> * Betr.: " [tryton] Request for Comment: Client manual" (Wed, 29 Oct 2008
> You didn't mention the meaning of the entries in italic font, what is it?
Wiki formating error without meaning. I correct this.

> Since the toolbar reflects just menu actions, those can be links to the
> related actions.
Yes, I will do.
> I would not include data types in widget presentation, this is too detailed for
> users.
Its not a user manual, its a Client reference, which explains the
using of the client in detail.

> I don't understand the meaning of
> Configuration
>   User
>   Report
> Here you break with the structure used so far. I think it would be best to
> follow the structure of the client as presented to the user. This would mean to
> put Configuration and Modules stuff under Main Window/Navigation
> Menu/Administration
Ok, you are right, I consider.

> Import and Export Data should go under their relative menu items, no need to
> mention once again.
yep, you are right.

> I am understanding this guide as an overview and reference over the clients
> functionality. If other smaller documents like "First steps" or "Quick start"
> are intended, they should link against this general document.
Yes, you are right. But they cannot be a main job for the tryton
project, because of maintainance problems. They needed to be
maintained and distributed separated. They are linked in the Section
"Sources and Links to other Documentation"

---

From: udono <[email-masked]>
Date: Wed, 29 Oct 2008 04:02:55 -0700 (PDT)

Thanks for the quick reply!

On 29 Okt., 09:45, Hartmut Goebel <[email-masked]> wrote:
> I would not appreciate a mote task- and concept oriented manual. Listing
> each menu item and each toolbar item is lengthy and of not much help.
> Esp. since toolbar entries are just shortcuts.
Yes, you are right, I combine them. I create  menu centric explanation
of the client. Each menu entry shows all shortcuts and toolbaricons.

> Keyboard usage is missing (or is this meant in "Mouse and Keyboard
> Accessibility"?)
Yes

> Leave off the Database menue for the Admin Manual.
As they are part of the client, so I would describe them there, I
think.

> Describe the concept of requests
Ok, I will do.

> Describe common graphical elements like the icons for tree- and list view.
> Widgets: go away from the types here. The user does not see any
> difference between most of the widgets (char, integer, ...)
Yes, you are right. The used fields.TYPES are not important by name.
But by identification (picture) and function.

>He has no
> notion about Many2One, One2Many and Many2Many. HE only _sees_ there are
> some icons beside the input field. Thus describe these concepts.
The client reference manual should be like a dry and boring ;-) to
read text, like unix man-pages where all general concepts of "using
Tryton client" are explained. All details of this books center on
'using the client'. The tryton client is heavily used by standard
user, as well as administrational user. But partially the client is
used by system admins (starting the client, administrating databases
from the client) and developer, developing new widgets or
modifications. There is a cut betwen the use and the developing the
client. But both should be linked together, to hinder duplicated
explanations.

> Perhaps had an section "for the impatient" descriping the concepts with
> are not common with most GUI programms (many2one, view-Switch, ...)
This need to be done by community. The client reference manual will
have a section to external documents/wikis/Informtions which try other
ways to explain the reference topics. Another idea of external
documentation could be a handbook which shows a typical financial year
of a company, oriented by the processes often used... But all of this
needs to be separated from the reference, because of easier
maintainance.

> Appendix: Is the config file relevant?
Its part of the client, so its relevant. Once again, the client Manual
is not a pure user manual, it is a client reference.

> Just my 2 cents
Overpaied by 3 cents ;-) thanx

---

From: Cédric Krier <[email-masked]>
Date: Wed, 29 Oct 2008 10:10:35 +0100

> So I would favour to migrate to a better wiki solution like mediawiki before

The documentation will not be done on the wiki, but it will be put in
the repository with the code. Because it must follow the evolution of
the code and we must be able to produce documentation for older release.
So the google wiki is just for development process, specific howto,
etc... But it must not become the main documentation for users.

-- 
Cédric Krier

B2CK SPRL
Rue de Rotterdam, 4
4000 Liège
Belgium
Tel: +32 472 54 46 59
Email: [email-masked]
Jabber: [email-masked]
Website: http://www.b2ck.com/

---

From: Cédric Krier <[email-masked]>
Date: Wed, 29 Oct 2008 09:55:49 +0100

On 29/10/08 09:45 +0100, Hartmut Goebel wrote:
> udono schrieb:
>
>> kindly I like to request comments for my concept of a client manual
>
> each menu item and each toolbar item is lengthy and of not much help. Esp. 
> since toolbar entries are just shortcuts.
>
> Widgets: go away from the types here. The user does not see any difference 
> between most of the widgets (char, integer, ...) He has no notion about 
> Many2One, One2Many and Many2Many. HE only _sees_ there are some icons 
> beside the input field. Thus describe these concepts.
>
> Perhaps had an section "for the impatient" descriping the concepts with are 
> not common with most GUI programms (many2one, view-Switch, ...)
>

Config file is just to store user preference, I don't that normal user
will need to edit it.

-- 
Cédric Krier

B2CK SPRL
Rue de Rotterdam, 4
4000 Liège
Belgium
Tel: +32 472 54 46 59

---

From: Mathias Behrle <[email-masked]>
Date: Wed, 29 Oct 2008 09:52:56 +0100

00:00:40 -0700 (PDT)):

Looks good so far.

Cheers,
Mathias

> Hi,
> http://code.google.com/p/tryton/wiki/DocumentationClient
> 
> On 2008-10-30 or a day later I like to start writing the manual.
> 
> Cheers Udo

---

From: Hartmut Goebel <[email-masked]>
Date: Wed, 29 Oct 2008 09:45:06 +0100

Widgets: go away from the types here. The user does not see any 
difference between most of the widgets (char, integer, ...) He has no 
notion about Many2One, One2Many and Many2Many. HE only _sees_ there are 
some icons beside the input field. Thus describe these concepts.

Just my 2 cents

-- 
Schönen Gruß - Regards
Hartmut Goebel
Dipl.-Informatiker (univ.), CISSP

Goebel Consult
Spezialist für IT-Sicherheit in komplexen Umgebungen
http://www.goebel-consult.de

---

From: Cédric Krier <[email-masked]>
Date: Wed, 29 Oct 2008 09:41:43 +0100

> On 2008-10-30 or a day later I like to start writing the manual.

It seems a good starting point.

-- 
Cédric Krier

B2CK SPRL
Rue de Rotterdam, 4
4000 Liège
Belgium
Tel: +32 472 54 46 59

---

From: udono <[email-masked]>
Date: Wed, 29 Oct 2008 00:00:40 -0700 (PDT)

Hi,

Cheers Udo