Application Manuals

[Gregory Leblanc <gleblanc cu-portland edu>]

Let me start out by saying this may be kind of a rant, as I've been
thinking about it for a while (and because neither nautilus or gnumeric
will compile for me tonight).  There have been a few people working on 
"Task Based Manuals" for some of the GNOME apps.  I've actually done a 
pretty thorough review of one of them, and it was shaping up into a very
nice manual on how to actually use the program.  However, I'm concered 
that people will start writing these -instead- of our traditional
application manuals.  I really think that we need both kinds of 
manuals.
The Application Manuals should cover what each element of the User
Interface does, with an explanation of nearly everything.  These 
manuals should get the first intense indexing work.  They are in place 
to server as a reference, for when you come across some element of the
UI that you want to use, but don't understand it's function.
The Task Based Manuals (for lack of a better term) should have a set of
steps to accomplish a number of tasks using the application.  These 
manuals would be pulled up when a user has a specific thing that they
need to get accomplished, and need to know how to use the UI to
accomplish this.  The steps involved in getting the task completed 
should include screenshots along the way, and should have extensive
linking to the Application Manual, for more detail on each of the
portions of the application that are used to accomplish the task.  I've gone through and looked at the software at work which has good
documentation, or for which we've found good documentation, and in just
about every case, there is both a good reference guide, and a second
task-based guide which work together to get people using the application
quickly, and still allowing them to get at all of the functionality that
the program offers.  Thoughts, comments, and criticisms welcome,

    Greg