Re: Application Documentation Guidelines/Web Page

[Alexander Kirillov <kirillov math sunysb edu>]

> From: Preben Randhol <randhol@pvv.org>
> Date: 07 Nov 1999 15:27:15 +0100

> 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. 
> 
> 1. It is cleaner, that is you will have the manual whether you have
>    installed the user guide or not.
> 
> 2. The user-guide would have to be updated a lot. There would most
>    likely be a gap between what the user-guide say you can do and what
>    you can actually do with the program if the user-guide is not
>    updated immediately.
> 

Well, I agree that there is no reason to put the documentation for
most applications - be it gnumeric or cd player - in the users
guide. However, I still feel that the core things - namely, panel and
desktop - should be covered in ug. After, desktop and panel are not
applications - they *are* GNOME itself, at leats from usres
perspective.  Probably, some coverage of gmc also should be there, but
maybe, much less detailed than it is now.

 As a compromise, I'd suggest leavin doc's for panel and desktop in
ug, keeping a short section about gmc, and adding a section which just
lists the applications and provides links to their manuals, as well as
says some general stuff (such as: in any app File|exit= ctrl q exits
the app). The sections on gmc, control-center, menu editor, applets,
cd-player should be turned into separate manuals; the section on gcal
should be merged with existing gcal manual.

I'd like to hear what Dave thinks about this - after all, he is the
principal author of users guide, and I suspect, if we do make such a
major revision of users documentation, he will have to do most of the
work...


Sasha