Re: Number of steps per procedure?

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.

Previous by Author: Re: What do we call this button?
Next by Author: Hiring Criteria, Writing Tests, and Drug Tests
Previous by Thread: Number of steps per procedure?
Next by Thread: [Fwd: Re: The OTHER Test]

What this post helpful? Share it with friends and colleagues:

Sponsored Ads