A question about writing instructions?

Subject: A question about writing instructions?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 7 Feb 2003 12:47:10 -0500

Becca Price asked for opinions on a house that writes out instructions in
narrative form rather than as steps: <<That is, rather than having step 1,
step 2, etc, an instruction might read (under a header like "Using the XYZ
Screen"): "To add an item to the data base, enter the specific information
and press Add. To locate an item already in the database, enter any
information you may have, and press Search. If more than one item matches
your criteria, you will see...">>

The problem with this format is that it makes it considerably more difficult
for readers to see the number and sequence of steps, and makes it
considerably easier for them to lose their position within the sequence. It
also makes it much harder to skim the documentation to find the particular
instructions they're seeking, since they have to skim entire paragraphs
rather than just the first few words of a paragraph; breaking out the "to
add" and "to locate" as subheadings greatly facilitates skimming, and if the
associated text isn't long enough to justify a full subheading, moving the
"to do x" to the beginning of its own sentence or paragraph at least
facilitates skimming by letting readers examine only the first few words
before deciding to proceed.

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada

"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer


Buy or upgrade to RoboHelp X3 today and receive the WebHelp
Merge Module for FREE ($299 value). RoboHelp X3's all-new
features include conditional text, completely re-engineered
printed documentation output, Context-sensitive Help Toolkit,
single-source layouts, and more!
Order online today at http://www.ehelp.com/techwr-l

You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.

Previous by Author: Teaching a writing class for co-workers?
Next by Author: Disclaimer or urban legend?
Previous by Thread: OT: mailing list for STC webmasters?
Next by Thread: 1099 work and employment taxes

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

Sponsored Ads