Format for instructions

Subject: Format for instructions
From: Sally Marquigny <SALLYM -at- MSMAILHQ -dot- NETIMAGE -dot- COM>
Date: Wed, 13 Jul 1994 16:37:00 PDT

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.


Previous by Author: Re: Advice sought re:office setup
Next by Author: Re: Do others miss "undigested" posts?
Previous by Thread: Re: Technical Writer Positions
Next by Thread: Re: Format for instructions


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


Sponsored Ads