Re. Deja voodoo? (Two versions of same application)

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Kevin McLauchlan wonders: <<...In my manual, I had explained initialization
steps and requirements by reference to the utility program.  That was the
command-line/console version.  Then, they wrote a (barely) GUI version.
Since I have to document both, I wrote the procedure "from scratch" for the
GUI version -- you know... to have a fresh look at it, and maybe pick up
things I'd missed or glossed over the first time.>>

Revision plus hindsight is a good idea, but the result (two different sets
of instructions for essentially the same thing) poses problems; apart from
the fact that each version has strengths that the other lacks, you've now
created a potential maintenance nightmare, since you now have two sets of
docs to maintain instead of just one. The simplest solution seems to be to
consolidate the two and create a single version, with three core sections in
it (in addition to standard stuff like tech. support information,
disclaimers, copyrights, warranties, glossaries, etc.): 1 = how to use the
console interface, 2 = how to use the GUI, and 3 = reference documentation
for each field or option in 1 and 2. In parts 1 and 2, just discuss how to
interact with the interface, not what the fields/menus/options mean; in part
3, combine the best aspects of each of the two docs into a single
consistently written section (one voice!) that explains the meaning of the
fields/menus/options, with "this works differently in the GUI" information
wherever necessary. Add a section at the beginning on the goal of the
utility and what people need to know before they get started, which
satisfies your "RTFM" requirement. Keep this as simple and short as possible
by concentrating on the meat (key concepts and overall metaphor for using
the product) and introducing the places where people are likely to err (but
referring them to the reference docs for details).

<<I know that most will just jump in and assume they'll get it right without
too much of that pesky reading>>

Then you should try to identify the main points where a typical user would
fail or go astray, and talk to the developers about how to prevent (or
minimize the adverse effects of) such failures.

--Geoff Hart, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca 
"The paperless office will arrive when the paperless toilet
arrives."--Matthew Stevens