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:"Virginia J. Link" <LINKVI -at- MAIL -dot- STATE -dot- WI -dot- US> Date:Wed, 30 Oct 1996 10:03:23 -0600
Can't give *supporting* doc for breaking out results of steps/actions into
separate steps, or failing to number steps, but Edmond Weiss' "How To Write
Usuable User Documentation," second edition, section 8.3.3.1, "Replacing
Prose with Structured Text," specifically addresses instructions buried in
paragraph form, and says "Whenever possible, multi-step procedures should
appear in itemized lists or word-tables."
Chapter 3, "Organization and Writing Strategies," in "Writing and Designing
Manuals," second edition, by Gretchen Schoff and Patricia Robinson, also
addresses the paragraph style/"linear mode" of stringing instructions
together "horizontally" in long, complicated sentences and paragraphs."
It may be that the "Dummies" in the book titles refers not just to the
purchasers of the books...or that "Easy" means not the way you learn to use
the software but the way they put the book together....
Virginia Link
Madison, WI USA
======================================================
Gang,
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.
I've been looking into several issues, but noticed that some commercial
software manuals (as in the Dummies books, XXX Made Easy, ABCs of XXX, and
similar series) often do not consistently or regularly number the steps.
I've always assumed that each numbered step should reflect an action on the
part of the reader. That is, if there are three things the reader must do,
there should be three steps. I've found that many books present the
information as
1. Select some text.
2. The text will appear highlighted on the screen.
3. Click the B button.
4. The text will be boldfaced.
5. Do something else.
with all kinds of numbered stuff that doesn't require action.
Alternatively, many present the information in paragraph form, as in.
To apply boldface formatting to text, select the
text, then click the B button. After you're finished,
do something else.
One book I sampled doesn't use a numbered list in about 300 pages.
Do any of you know anything about the various schools of thought or
usability tests that would support either of the second two examples? I
personally REALLY object to the numbered non-steps, and think that the
paragraph approach leaves a lot to be desired, but someone's blowing a lot
of money on publishing these books -- comments?
