Re: Need doc set advice

Subject: Re: Need doc set advice
From: Mike Pope <mikep -at- ASYMETRIX -dot- COM>
Date: Thu, 28 Jul 1994 12:41:00 PDT

>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
>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.
> folks in the field like to use the Tutorial for training, so I can't dump

>I'm toying with the idea of converting the Reference Manual to a
>format. Instead of having chapters called File Menu, Edit Menu, etc., I'd
>have chapters like Searching, Updating, etc. This piece would be the
>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
> User's Guide would be redundant?

Is the tutorial itself organized by tasks? Does it have the same sections
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
do the 6, 12, 22 most common things that ones does with this program. I'm
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
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
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
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
> 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

Previous by Author: Re: What the f -at- #$?
Next by Author: Screen Shots
Previous by Thread: Need doc set advice
Next by Thread: Word Mac/Windows indexes

What this post helpful? Share it with friends and colleagues:

Sponsored Ads