Format for instructions

Subject: Format for instructions
From: Richard Sobocinski <"Richard_G_Sobocinski%~WHC207"@CCMAIL.PNL.GOV>
Date: Thu, 14 Jul 1994 09:22:00 -0700

When Glen said he was writing instructions for
"techno-dweebs", I took it to mean that they were already
familiar with the system in question and that he was
providing task oriented procedures. In that case, I don't
think you want to clutter up the "task" stuff with background
or explanatory stuff. It's much easier to perform a task by
following a "to do" list than it is to pick out the actions
from a block of "why you're doing it" text.

rxs459 -at- fep1 -dot- rl -dot- gov
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

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

Previous by Author: Flame me, I'm Italian
Next by Author: So who is truly tougher?
Previous by Thread: Re: Format for instructions
Next by Thread: Did too did not

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

Sponsored Ads