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.
What an interesting scenario... Tom, I don't envy you the task of
documenting a command-line interface for an audience that includes novice
users! :)
I would probably phrase that step something like this (I'll also use a
little HTML to indicate formatting, as you did):
1. In the <b>xterm</b> window, type:
<b>cd /dat/<i>client##/client name/protocol</i>/work</b>
For the italicized parts, substitute your specific client number, name,
and protocol: for example,
<b>cd /dat/client35/methos/my25-17/work</b>)
2. Press <b>Enter</b>.
I would probably append the "come back up one level" instructions to the end of
the discrepancy report instructions, so that in each module, the user winds up
back where they started, ready for the next set of instructions.
I have a bias toward writing for novices. In my experience, the novice users
usually outnumber the intermediates and experts: most people learn just barely
enough to do their jobs, especially in applications that they don't use
constantly. Expert users might get impatient with the kind of instructions I
wrote above, so perhaps for them I would include a quick-reference sheet in an
appendix with the most frequently used commands. The experts probably won't be
poring over the documentation as much anyway. I'd rather bore the experts than
leave the novices underprepared.
To expand on what I said at the start... I would hate to put novices in a
situation where they had to navigate a command-line interface. If that's what
they will be doing frequently, they can't stay novices or they'll be goofing up
left and right. Perhaps a short primer on the commands and the directory
structure (w/illustrations) would help them learn the ropes.
I got a kick out of your real-life learning examples. Been there too. Screen
captures have to match the screen exactly, since novices can't always
differentiate significant deviations from glitches and inconsequential details.
And your observation about their not reading steps all the way through is right
on target. A classic example someone brought up a while back was (paraphrasing)
"Press the Format button to format your hard drive. Note: This will erase your
files." Half the users will read as far as "Press the Format button" and, having
identified a concrete step, will go ahead and press the Format button. Awfulness
ensues. But rather than telling them to read all the way through--who knows if
they'll even read the part that says "Read all the way through!"--why not
structure every step so that users don't jump the gun?
If users keep falling into the alligator pit, there are two options: try to
change their behavior (put up a warning sign), or change the environment to
accommodate their behavior (put up a barrier so they can barge around more
safely). I would try to change the environment instead of the users--it's more
efficient and reliable. In that example, I'd probably write "If you want to
erase your files, press Format. WARNING: this permanently deletes your files."
And I'd be lobbying the developers to relabel the button with something that
novices will understand, like "Erase all files"... and tuck the button away
somewhere where they won't run across it unintentionally.
My two cents...
Christine
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Announcing new options for IPCC 01, October 24-27 in Santa Fe,
New Mexico: attend the entire event or select a single day.
For details and online registration, visit http://ieeepcs.org/2001
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
---
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.
