Re: Users Guides vs. Help

[Dan Mueth <d-mueth uchicago edu>]

I just realized this points to a larger question with the Gnome
Documentation: 

Should every application have a Users Guide?  If so, what should the Users
Guide look like?  Should it describe each window and all the buttons (as
the "Help" screen for each page would do)?  Is there a standard outline
for Users Guides? (or should there be?)

And a side question: Should the "Help" page for each window have
screenshots in general, even in cases where confusion is unlikely? I've
noticed some documentation uses screenshots gratuitously while others
don't use screenshots at all.  They seem to make the Help screens look
nicer, but could become a burden on disk space and the maintainers who
have to update all the screenshots whenever a new button is added to the
application.  

Are these questions addressed in existing documentation guides?  If not,
maybe they should go into "The GNOME Handbook of Writing Software
Documentation." 

Dan

> Hi,
>   I have noticed than many applications (eg. gnomecard and gnomecal) have
> a Users Guide in addition to having "Help" buttons (eg. in the preferences
> window).  Currently, many applications with a Users Guide do not have
> anything at "properties-0.html" etc. where the "Help" buttons would
> connect to.
> 
> Is the solution:
> 	1) change the "Help" links to point to pages of the Users Guide
> or 	2) write a separate set of pages for "Help" and Users Guide
>  
> ???
> 
> 
> Dan
> 
> 
> -- 
>         FAQ: Frequently-Asked Questions at http://www.gnome.org/gnomefaq
>          To unsubscribe: mail gnome-doc-list-request@gnome.org with 
>                        "unsubscribe" as the Subject.
>