Re: Application Documentation Guidelines/Web Page

[Dan Mueth <d-mueth uchicago edu>]

> > 
> > 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.  
> > 
> 
> Of course, every application must have a "Help" button which brings
> the manual on screen. However, I'd think it is OK if in fact this
> "manual" is just a part of users guide and not a separate document -
> for example, this is what is done with control-center. The only
> difference is that it is distributed in the package "users-guide-*"
> rather than "gnome-foo-*"

The reason to put the documentation in the same package as the application
is to guarantee that a user has the current documentation for the version
of the applications on his machine. If we can assume that somebody will
have a copy of the user manual, and that he updates it whenever he gets
new Gnome packages, then having the docs contained in users-guide-* is
fine.

> >Really, the User Guide would just pull the Manuals
> >together, creating a single larger doc.  
> 
> Do you mean  that the users-guide should  just contain links to the
> html files distributed with other applications? Then there are
> problems with things like table of contents: either we include all
> links, and then for some users some of the links do not work, or we
> have to "build" the users guide for each user separately, which makes
> life somewhat more complicated. Or, of course, we could just copy the
> html files from each application - but this menas really wasting
> hard disk space and bandwidth. 

Okay.  Let me suggest a somewhat different idea from my previous one...

I expect each application will have a reasonably detailed Manual.  This
would be the most complete and up-to-date documentation available on
"foo", and should be accessible from the "Help" menu.

If "foo" is an important and commonly used app, the User Guide will also
want to discuss it. As discussed previously on this list, it may be a good
idea to make the User Guide brief. (This assumes the User Guide is
designed to be an introductory manual for newbies to read in a single
sitting, as opposed to a Reference Manual.) In this case, the User Guide
may use an abridged copy of the Manual which would need to be maintained
separately from the Manual.

Rather than having the User Guide incorporate the full Manuals of
important apps, it may be better to have an additional text, such as a
"GNOME Reference Manual" or "GNOME Application Index" which would compile
all GNOME Manuals into a single document.  It would probably be best if
this was generated on-the-fly, based upon the applications currently
installed on the local machine.

This would give a more uniform appearance to the user.  If they want to
learn only the basics to get started, they go to the "User Guide". If they
want an index to all apps, they go to the "GNOME Application Index", which
has the complete documentation to each application on the system. If they
are in an application and go to help, it only gives them the Manual for
the current application.

> As for status of gmc, menu editor and others: they do have manual
> (this manual is a part of users-guide, same as for control-center)
> they just do not have "Help" button linked to it. I thought, this is
> exactly why you have 2 columns in your status: one for existence of
> manual, the other for existence of the help button. 

Yes.  I should revise my column labelling to more precisely describe the
procedure I used or else add more columns to provide a more detailed
description of the documentation status.

Cheers,

Dan