Re: Application Documentation Guidelines/Web Page

[Preben Randhol <randhol pvv org>]

Dan Mueth <d-mueth@uchicago.edu> writes:

| I would like to hear people's opinions on this web page and make sure
| everyone agrees with the section:
|            GOALS AND GUIDELINES FOR APPLICATION DOCUMENTATION
| 

My opinions (those I don't comment on I agree with):

   Goals and Guidelines For Application Documentation 

   General Applications 

           All applications should have a Manual, accessible under the
           Help menu. (except extremely simple ones.)

Cut (except extremely simple ones.) I think that it doesn't matter if
it is simple or not. If it is the manual would be only half a page or
something. Also standard information like where to report bugs should
go into the manual as an requriment. Thus the manual should at least
contain this. The same for Applets.

           All preference windows (and other configuration windows)
           should have "Help" buttons, which connect either to the
           relevant page of the Manual, or other documentation.

Yes, but I would also like to have help buttons on other parts of the
program too. Say I make a program where one can enter ones cooking
recipes. I have a page where one enters the different ingredients
amounts and units along with the description. The units might not be
clear to some (say I don't use English units as default). Then it
would be very nice if one had a Help button for that page that opens
the manual where this page is explained.


             For small applications, the top level of the document
             should be <sect1>. For larger applications, it should be
             <chapter>. (This allows us to compile all documents into
             a single work.)

Are you talking about _all_ apps or just the main Gnome apps?


             All documentation should be included in the application
             package. (Do not rely on documents only available on the
             internet.)

I very much agree with this one as I have an off-line computer myself.


-- 
Preben Randhol                 Affliction is enamoured of thy parts, 
[randhol@pvv.org]              And thou art wedded to calamity. 
[http://www.pvv.org/~randhol/]                    -- W. Shakespeare