gEDA-user: Verbosity in gEDA/pcb documentation

[Stefan Salewski <mail@xxxxxxxxxxxx>]

Hello,

I spent some time reading gEDA/pcb documentation in the last weeks.

Good user-documentation is very important, and I have the feeling that
gEDA/pcb documentation has made some progress in the last months.

But is it really a good idea to use much redundancy and verbosity?

Example from Pcb-20070208 pdf document:

>This is one of the command box helper actions. While it is a regular
>action and can be used like any other action, its name and syntax are
>optimized for use with the command box (:) and thus the syntax is
>documented for that purpose.

I read this text ten times in the manual.

>This is one of a number of actions which are part of the HID interface.
>The core functions use these actions to tell the current GUI when to
>change the presented information in response to changes that the GUI
>may not know about. The user normally does not invoke these directly.

The above text can be found 5 times.

Similar redundancy I have seen in gschem wiki documentation.

Copy and paste makes it very easy to produce such sort of verbose
descriptions. For people who read only some small parts of the docu,
this may be no problem, maybe it is really helpful? But it makes the
documentation longer and less concise. And for people who tries to
really understand gEDA/pcb by reading the whole documentation, this sort
of verbosity may be a pain.

Best regards

Stefan Salewski




_______________________________________________
geda-user mailing list
geda-user@xxxxxxxxxxxxxx
http://www.seul.org/cgi-bin/mailman/listinfo/geda-user