Re: Single-step procedures

[Robert Plamondon <robert -at- PLAMONDON -dot- COM>]

I'm not sure the discussion make a proper differentiation between
procedures that are read for content and ones that are literally
followed step by step.  Some tasks -- most software tasks, for
instance -- can be performed with the book open in front of you.

On the other hand, many hardware tasks require that you do things
that can't possibly be done with the book open in front of you.
You perform a step, wipe the worst of the grease off your hands,
return to the book, find your place, and read the next step.

Such procedures MUST be formatted in such a way that the steps
are very clearly delineated.  The steps pretty much have to be
numbered if the user is to find his place again.  Careful workers
also put a checkmark after each step as they perform it.

Burying steps in ordinary paragraphs as a way of avoiding the
numbering issue is simply not an option in this case.  All steps
have to be presented with the same visual cues, or the work isn't
going to be done correctly, even by a careful worker.

To those who say that a foolish consistency is the hobgoblin
of small minds, I reply: "Partial credit will not be given
if the bridge falls down."  There's a big difference between
a step in a tutorial, where the only risk is time (the user will see
that the results are wrong, backtrack, and eventually find the
buried step) and a step in, say, an engine rebuilding manual.

For manuals dealing with critical procedures, all procedures and
all steps must be flagged the same way.  I'd recommend that a
single-step procedure be prefaced with the paragraph:

"This procedure consists of a single step:"

It might also be useful to use something to mark the end of
each procedure in a completely unambiguous way.  A dingbat used
at the end of a procedure would be good.  (A page break is not
good, since a procedure may be more than one page long.)

        -- Robert

--
Robert Plamondon, High-Tech Technical Writing, Inc.
36475 Norton Creek Road * Blodgett * Oregon * 97326
robert -at- plamondon -dot- com * (541) 453-5841 * Fax: (541) 453-4139
http://www.pioneer.net/~robertp

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html