Re: Need doc set advice

[Mike Pope <mikep -at- ASYMETRIX -dot- COM>]

>I'm documenting a fairly simple GUI application for users who are not
>particularly knowledgable about using software. Users can fill in forms to
>search a database for information and update that information. When I
started
>this job, the doc set consisted of the following pieces:

>Reference Manual, organized by menu
>Tutorial, organized by major task
>Quick Reference Card, organized by task

>Users complained that the Tutorial was too long and intimidating, so I
wrote a
>Quick Start manual.  This piece presents a subset of the tutorial.
 However,
>the
> folks in the field like to use the Tutorial for training, so I can't dump
it.

>I'm toying with the idea of converting the Reference Manual to a
task-oriented
>format.  Instead of having chapters called File Menu, Edit Menu, etc., I'd
>have  chapters like Searching, Updating, etc.  This piece would be the
receptacle
>for all information about the application, from soup to nuts.


>My questions:

>o Given that I have a fairly detailed Tutorial, do you think a
task-oriented
>   User's Guide would be redundant?

Is the tutorial itself organized by tasks? Does it have the same sections
you
are proposing for the task-oriented-no-longer-a-reference manual?

This is speculative, but I would see the Tutorial as a walk-through: watch
me
do the 6, 12, 22 most common things that ones does with this program. I'm
not
going to go into exhaustive detail, I'm just showing you some stuff. If
you're clever,
or if you've done some of this before, this may be all you need to get
going.
The task-oriented section, on the other hand, presents the conceptual
background required to understand the purpose of the procedures.
"What does it mean to search?" "What does it mean to sort/order data?"
"What is an index?" etc.  This section would also be more exhaustive -- if I
showed
you the 12 most common things in the Tutorial/Walkthrough, well, here's
where you
learn the rest. To save trouble, you could theoretically refer them back to
the
Tutorial for procedures already covered there. That might not be as odious
as it sounds,
since most people are probably not slogging through the task-oriented
section page by
page; they are probably just looking for one procedure, and the index can
take them to
the Tutorial instead of to this section. Dunno, you'd have to try it.


o How valuable do you think the menu-based organization is for a fairly
simple
>  GUI application?

The presumption of such a section is that they're staring at the screen and
are wondering
about something they see there. "I chose Edit-Find, and now I don't know
what Match Case
means". I assume, anyway, that that's what the sort of information that the
section contains.
If so, that type of information is more typically provided in online Help,
especially if you
can provide hypergraphics that allow people to click on the prompt or
whatever that they're
confused about.

Just thinking out loud. I might be misinterpreting your questions, and
extrapolating a
bit too freely from your descriptions. If so, just pay me no never mind.

 -- Mike Pope
mikep -at- asymetrix -dot- com