Format for instructions

[Sally Marquigny <SALLYM -at- MSMAILHQ -dot- NETIMAGE -dot- COM>]

Few things are more frustrating for users of *any* level than strings of
facts that are apparently unrelated or unprioritized.  Telling a user,
regardless of technical background, "A requires module B in C mode. D
provides the input for E." doesn't tell them how A, B, C, D, and E relate or
most importantly *why* these statements are true or what the results are of
following or ignoring them.

When I write documentation, I try to empathize with the user, of course.
Like a broken record, I repeat after nearly every crumb of information, "Why
do I need to know this?"  Answering this question *in the text* not only
assures that I've covered the topics fully, but also frequently helps me to
see the best format for that particular factoid (or the whole concept, or
whatever).


Sally Marquigny                    Network Imaging Systems
sallym -at- msmailhq -dot- netimage -dot- com       Herndon, VA

 ----------
From: TECHWR-L
To: Sally Marquigny
Subject: Flame me, I'm Italian
Date: Wednesday, July 13, 1994 2:23PM

I write lots of manuals for techno-dweebs.  Consequently much of what I
write
involves "instructions" such as:

  -  A requires module B in C mode.
  -  D provides the input for E.
  -  etc.

Would statements such as the above be better written as actual instructions?
That is "To make A work, start module B in C mode" or "Take the results of D
and input them to E."

For user's manuals, I'm very careful to write _instructions_: do A, do B,
then do C, and I try to avoid constructions such as the above.  Is the same
style as necessary for "high-end" users?

 ------------
glen accardo                         glen -at- softint -dot- com
Software Interfaces, Inc.            (713) 492-0707
Houston, TX 77084

Nuke the unborn, gay whales for Jesus.  Flames to /dev/null.