Re: Application Documentation Guidelines/Web Page

[Neil D Matthews <Neil Matthews sonydnse com>]

Preben Randhol wrote:

> Alexander Kirillov <kirillov@math.sunysb.edu> writes:
>
> | Some comments:
> | 1.     >All documentation should be included in the application
> |        >package.
> |
> | Or in a users guide. For example, gmc is very well documented in
> | users-guide: there is no need to duplicate this in a manual. Same for
> | many applets, menu editor, and more. (BTW: I think that you should
> | really change the status for gmc and menu editor to "Manual=1")
>
> No. Every app should have it's own manual.

I think that this is right --- however, one might take an approach similar
to, say Linux Gazette, where the application documentation consists of a
specific and a base part.

The base part would basically (once) document that File -> Exit means exit
the application, etc., etc. The base part might also include other useful
documents, etc. e.g. the GNOME FAQ, users-guide, generic gnome manual page,
current web-sites, etc., etc.
Actually, this could potentially be included in gnome-core?

The specific part would just document the application specific options.

This should reduce the amount of boring repetitive documentation that needs
to be written. Although it does require more thought in designing "a
documentation system", rather than individual documents, and may bring in
some implications for versioning.

----------

Neil Matthews.