Re: Application Documentation Guidelines/Web Page

[Dan Mueth <d-mueth uchicago edu>]

> 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

My opinion was that if a user is running application "foo" and has a
question, he/she should be able to go to the "Help" menubar and get an
application-specific Manual.  All "foo"-specific documentation should be
in this Manual.  

The User Guide would want to include the content from the Manuals of the
standard GNOME applications.  From the user's perspective, this would be
duplicating the docs.  Really, the User Guide would just pull the Manuals
together, creating a single larger doc.  

> really change the status for gmc and menu editor to "Manual=1"

The criteria I used in creating this Table was that of an end user:

1) If I go to the "Help" menubar, is there a Manual explaining how to use
this app?  (ie. does the "Help" menubar do as advertised?)
2) If I go to a configuration window, are there "Help" buttons?  If so, do
they pull up a relevant document?

I imagine in many cases, applications were rated as 0 based on these
criteria even though good docs exist somewhere. From a practical point of
view, great docs don't do much good if the user can't find them easily.

This is one of the points which I'm hoping to get feedback on.  Are these
good criteria?

> More complicated: what to do with
> rp3? It is also documented (in RH users guide), but this is not a part
> of gnome...

I expect there will be many apps that are not in GNOME CVS, but are GNOME
compliant.  I think it is fine to include them on this page and have
people document them. (If we put "foo" on the list and give it 0's, people
will be more inclined to fix/document it.) The authors should be contacted
before the docs are written to make sure the author is willing to accept
the docs in the finished product.

> 2. Add: all screenshots should be in PNG format. > 
>
> Sasha

Yes.   I'll add this.

Thanks for the feedback.

Dan