Re: theory behind document usage; sage input please.

[k k <turnleftatnowhere -at- yahoo -dot- com>]

My opinion (not exactly *sage* but not quite parsley
either):

You ain't talking about the average user guide. You
are producing documentation for software that is used
when people are in real emergencies. Your
documentation may make the difference between injured
people getting the help they need in time or too late.
Err on the side of caution.

One problem is personnel turnover at the user site.
You can't be certain that the people who went through
the training will still be there next month. The guy
who comes in the week after training ends won't be
able to pick up the basics in that training.

Also, the users won't use the documentation the way
you want. A lot of times when people want information,
they aren't going to read the doc pages in the order
you want them to read. They'll jump straight to the
page that has the most relevant title and won't even
think to look anywhere else. If they are in a hurry
and/or under stress - and with the kind of situations
they'll be dealing with they probably will be - they
may forget what they were shown in training and they
will NOT want to jump back and forth to find
information. They will want and need everything for
the procedure of interest in one linear package right
in front of their eyes. Once they are more familiar
with the software, when they open the doc they will
skip past the baby-step stuff with no loss.

In a manual for the kind of software you describe,
cross-references are fine as long as they are
*additional* information, something that may be nice
to know but is not critical to the procedure
immediately at hand. Having such cross-refs may not be
useful but I can't see it hurting.

I think the section numbering probably doesn't help
you any. Simplify the cross-refs - just give a page
number and don't bother with the section numbers or
section titles.

You may want to break the manual in two:  a quick
reference guide that contains nothing but detailed
procedures, and a reference manual that provides more
detailed background information. 



__________________________________
Do you Yahoo!?
Yahoo! Search - Find what you?re looking for faster
http://search.yahoo.com