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: Number of steps per procedure? From:Dan Emory <danemory -at- primenet -dot- com> To:"Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>, "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Wed, 18 Oct 2000 17:32:42 -0700
As Geoff Hart (and a few others) have pointed out, if it takes 19 steps, it
takes 19. Rules limiting tech writers to some arbitrary maximum number of
steps are absurd. If such rules are to be enforced, they must apply to the
designers of the product or GUI, not to the tech writers.
I disagree with those who suggest a "chunking" approach in which a
procedure is broken up into separately titled (and typically unnumbered)
chunks, and the step numbers are reset to 1 within each chunk. This is an
invitation to error, because the user is almost certainly going to
interpret this as allowing him/her to start at whatever "chunk" (s)he
thinks is most appropriate under the circumstances. Caveats at the
beginning of a lengthy chunked procedure of this type warning users that
they must perform the entire procedure from start to finish won't do the
trick, because the user is likely to go right past that warning while
looking for the chunk (s)he thinks is most appropriate.
Obviously, chunking that is accomplished by breaking up a procedure into
sequentially numbered steps and substeps is the best approach. I strongly
disagree with those who suggest that substeps should be bulleted or
otherwise unnumbered. In a 19-step procedure, the step numbers should be
consecutively numbered from 1 thru 19, and the substeps (if any) should be
numbered sequentially under each step with lower-case letters, not bullets.
This forces the user to realize that the entire procedure must be performed
sequentially from the first to the last step, and, within each step, the
substeps must also be performed sequentially from first to last. Bulleted
lists of substeps are often interpreted by users as "pick and choose"
lists, or that the items in the list don't have to be performed in any
prescribed sequence.
Also, to clearly distinguish procedural steps from other types of numbered
lists, I favor prefixing step numbers with the word "Step" to avoid any
ambiguity. This is easy to do with the autonumbering specifications in
FrameMaker.
The prevailing doctrine that numbering things intimidates users is not only
absurd, it's wicked. I suspect that this abhorrence of sequentially
numbering things arises from the fact that MS Weird is predominant, and we
all know of its nasty proclivity to screw up autonumbering.
Another point in favor of sequential numbering: There are often cases where
a point is reached in a procedure where, based on what was found at that
point, a procedural jump may be required. An instruction that states:
"Perform steps 6 thru 9 in paragraph 6.1.1, and then return
to this procedure and proceed step 8c"
is far more explicit (and thus less confusing) than:
"Perform Steps 1 thru 3 under the chunk entitled'Tweaking
the Thingamajig' in the procedure entitled 'Installing the
Whatchamajigger', and then return to this procedure and proceed
to the third bulleted substep of step 4 under the chunk entitled
'Retweaking the Thingamajig'".
Here are two more arguments in favor of sequentially numbering all steps
and substeps:
1. Very often, two or more people are involved in performing a procedure,
and those people are physically separated from each other. Each is reading
from their own copy of the procedure, but they must communicate with each
other by talking, shouting, or using an intercom or telephone. I can think
of many examples of this, perhaps the most common being a user who is
getting help via telephone from a help desk or technical support. In these
circumstances, the fundamental requirement is for all parties to stay in
sync, and the best way of doing that is by explicitly referring to page,
paragraph, step, and substep numbers.
2. It is common for users to make up checklists to assist them in
performing complex procedures. The checklist, which identifies each step
and substep in the procedure, is used to record that each step or substep
was completed, and also to note any discrepancies or comments relevant to
each step. But if such procedures have untitled chunks where the step
numbers in each chunk restart at 1, and substeps are bulleted instead of
numbered, making up a checklist and following it is far more difficult.
And finally, if complex, lengthy procedures appear in an on-line help
document, the user hasn't a prayer of performing it quickly and properly
unless he/she can first print out the entire procedure. If, as is often the
case with HTML help (and other types of unpaginated, non-PDF on-line help),
it's not easy to selectively print out the requisite pages, and/or if the
printing of such pages makes a mess of the procedure (perhaps even omitting
text at page breaks), then the on-line help must be supplemented (or
replaced) by printed manuals.
====================
| Nullius in Verba |
====================
Dan Emory, Dan Emory & Associates
FrameMaker/FrameMaker+SGML Document Design & Database Publishing
Voice/Fax: 949-722-8971 E-Mail: danemory -at- primenet -dot- com
10044 Adams Ave. #208, Huntington Beach, CA 92646
---Subscribe to the "Free Framers" list by sending a message to
majordomo -at- omsys -dot- com with "subscribe framers" (no quotes) in the body.