TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
Rich
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
whatever).
Sally Marquigny Network Imaging Systems
sallym -at- msmailhq -dot- netimage -dot- com Herndon, VA
