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.
Subject:Re: Procedural Steps From:"Susan W. Gallagher" <sgallagher -at- EXPERSOFT -dot- COM> Date:Thu, 31 Oct 1996 10:58:29 -0800
>Eric Ray asks:
>> I've been doing some research into using procedural steps, as in:
>> 1. Select some text.
>> 2. Click the B button.
>> 3. Do something else.
Well, I know of no *formal* usability studies -- but I wrote and delivered
classroom instructions for about seven years. Nothing teaches you how to
write instructions more clearly than taking what you've written into the
classroom and watching your students use the instructions you've written.
(OK, sounds like a usability study. Back then we called it work)
What I learned is...
* Never number a non-step. If there's a number, there must be something
to do and the poor users will read and reread the step until they
uncover the mystery of what you want them to do.
* Never embed instructions in a paragraph. Paragraph text can *always*
be skipped because it just tells you stuff that you're more apt to
discover by doing.
* The "feedback" information, such as "the dialog box opens" is important.
It prompts whoever is following the instructions to look at the screen.
Without feedback, users will blindly follow instructions, usually with
disasterous results. For novices, writing the feedback as a question
(e.g. Did the blah-de-blah dialog box open?) is often useful.
* The two-column approach is OK for more advanced users, but novices
"notice" the feedback, etc., if it's in-line with the instructions.
Also, in a book that's only 7 inches wide, you may only have a 4 or
4.5 inch line to work with making two columns too narrow to be read
When I was writing for novices, I did things this way:
1. To create bold text:
Highlight: the text to be bolded
Click: the B button on the toolbar
Did the selected text become bolded?
2, To apply the italics attribute to the same text:
Verify: the text is still highlighted
Click: the I button on the toolbar
Is the text now bold and italic?
I now write for advanced users, so I don't break down instructions into
such small fragments. The same instructions for advanced users might look
To apply bold and italic attributes to text:
1. Highlight the text to be bolded.
2. Click B on the toolbar.
The text is bolded.
3. To italicize the text also, verify that the text is still
selected, then click I on the toolbar.
The text is now bold and italic.
Note, I don't use any typographic conventions to distinguish feedback
paragraphs. I do, however use 6 points between steps and feedback and
a full 12 points between feedback and the next step. This associates
the feedback to the preceeding step visually.
sgallagher -at- expersoft -dot- com
-- The _Guide_ is definitive.
Reality is frequently inaccurate.