How much is too much?

Subject: How much is too much?
From: Geoff Hart <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "Techwr-L (E-mail)" <TECHWR-L -at- lists -dot- raycomm -dot- com>
Date: Mon, 14 Feb 2000 09:53:57 -0500

Kevin McLauchlan wondered <<Do you advocate (or, demand, if you're a boss)
that lists of instructions never exceed a certain number of consecutive
steps? Do you have "never-exceed" guidelines for how much explanatory stuff
can (or
should) be embedded in an instruction list?>>

Nope. But if I encounter a huge list of steps, I'm very strongly motivated
to break it up into smaller chunks just to ensure that the procedure doesn't
seem so intimidating. It's like weightlifting: doing 120 reps is a scary
proposition, but if you break it up into 3 sets of 40 or 4 of 30, the work
seems an awful lot more manageable. (In appearance as well as in fact!) Most
long procedures can easily be broken up into subtasks, with "take a break
and wipe your forehead; it's safe to stop for a moment" positions midway
along the way.

<<I heard/seen people claim that any more than 5 (or 9) numbered steps is
too many, and the procedure should be
broken down into smaller chunks. Hoo-boy! I'm well into the twenties and
still going, here.>>

The 5-9 range is based on a misunderstanding of George Miller's research on
short-term memory ("The magical number 7 plus or minus 2"). Someone, way
back in the dim depths of time, incorrectly understood Miller's work and
used it to justify such a restrictions, and the resultant "rule of seven"
has spread like kudzu through technical communications ever since. Miller's
work _doesn't_ apply to procedures composed of series of numbered steps (or
at least not in this simplistic a manner).

<<I've also heard that explanation has no business in the middle of a
numbered list of steps.>>

This assertion is more defensible, but not inevitably correct. In a
tutorial, you often want to help users learn the reasons for doing things so
that they can think about how to solve problems on their own; learning "why"
can be much more powerful than learning "how" when it comes to mastering a
program. So if you're creating a tutorial, mixing explanation with procedure
can be a very good thing indeed. Conversely, if readers already know much of
the theory and just want numbered steps to help them remember the sequence
of steps, then explanations and other digressions become intrusive and
interfere with getting the job done. There are many situations in between,
but on the whole, these are two useful extremes that you can use as
benchmarks for any given procedure: which parts of the procedure require
explanation, and which ones just need to be done, blindly, even if the
reader doesn't understand them? When can readers spare the time to read the
explanation, and when should they read the explanation before they even
contemplate starting the procedure?

<<The procedure is a sequence of steps that, once started, may not be
abandoned, and should not be interrupted/delayed. Elements of the system
will timeout, and you'll be back at almost square one.>>

In a case like that, you need to start the procedure with a brief
explanation of the context and list of what the user will need to complete
the task. For example: "Once you begin this procedure, you must complete it
without stopping; if you're forced to stop, you'll have to start all over
again, and may damage the machine. Obtain the following tools before you
begin [list of tools]. In addition, you must know the answers to the
following questions before beginning: [list of the decision points the user
may encounter that require preparation or research rather than simply
answering the question blindly.] Good luck, Mr. Phelps. This tape will
self-destruct in 20 seconds."

From your description of the application, it sounds like the users need a
tutorial on the many options they'll meet along the way, and the cautions
that accompany each option. These are emphatically _not_ things they should
encounter for the first time when they're in mid-procedure. Given that the
procedure becomes substantially more complex if they run out of time and
have to restart with a partially reconfigured device, you need to prepare
them as well as possible before they even start; that way, they're likely to
either know the answer to each question that arises or be able to figure out
the correct answer quickly, with no pressure and little or no risk of error.
One thing I've done in similar situations is to provide a "planning guide",
which is nothing more than a simple one-page worksheet that the user can
photocopy and fill out before they even begin the process. (The current one
I've developed occupies a two-page spread, with a flowchart on one side to
show the decision points, and a data sheet on the right to record the
decisions.) When the user encounters each decision point during the "live
fire" exercise, all they need to do is look at the worksheet for the answer.
No muss, no panic, no delays, and away they go. Moreover, if they screw up,
they can review their data sheet and see where they went wrong.

<<If you screw up partway through, the device you are preparing is left in a
useable state -- it can still be initialized -- but it's no longer a
"virgin", so even if you re-start from scratch you'll encounter some
conditions that don't quite match those that are expected if you went
through properly the first time around.>>

That's an interface problem, and a bad one. If you can't persuade the
developers to include a "reset" button that lets the user restart from
scratch, or a similarly simple fix (e.g., remove the battery, count to 10,
and voila! it's back at the default setup), then you need to provide an
appendix that explains how to reset to this point. (That's probably useful
no matter what gets done about the interface.) If you're stuck trying to
solve the interface problem through documentation, then you need to
carefully analyze how users are likely to fail and provide tools (e.g., the
worksheet) that help them avoid failing. One thing that might prove useful
is a "fill in the blank" software wizard: the users enter the decision-point
data before they ever launch the application, hit the "start" button, and
let the device configure itself based on the data they provided. That won't
work if every decision point is dynamic (e.g., if the utility reads the
value of some gauge or sensor and requires an answer based on that value).

<<If you make certain incorrect (though they may very well be correct for
somebody else) choices, then once the device goes operational, you may have
screwed yourself -- at least for your particular circumstances.>>

Then you need to include a troubleshooting guide; in particular, you need to
provide the "reset to default" information I proposed, and a means of
testing the final configuration to ensure that it's what you intended. Have
a look at the "post mortem" reporting functions from software such as Norton
Utilities for a simplistic approach ("here's what you did... you can't do
anything about it now, but at least you know what you did"). Look at
monitoring applications (e.g., network software) to see more sophisticated
approaches.

<<Multi-million-dollar livelihoods and corporate reputations can depend on
doing this stuff correctly.>>

Then you've discovered a major usability problem and a potential source of
very expensive liability lawsuits. Point out to your manager that the first
customer who loses a "multimillion dollar livelihood and corporate
reputation" because the application doesn't protect it from such losses is
going to sue them faster than they can scream "IPO". Nothing may get done
about this in version 1, but it can become a priority for version 2.

<<Our product is a hardware-based enhancement to other people's (companies')
applications>>

Don't know about you, but it makes me acutely uncomfortable to be working
under a timer, knowing it could cost a million dollars if I screw up, and
having to hope that the "other people's applications" work the way they're
intended. Did someone say "bomb disposal unit"? <g>

<<So, what I did was give a "preview" list of "this is what you'll be doing,
and PLEASE pay attention to all the Cautions, Warnings and Caveats", and
then I jumped in with more than fourteen pages, 23 numbered steps and all
sorts of side-bars, text boxes and just plain "Numbered-list-continued"
paragraphs, to get through it all. Oh, and screen-shots. Lotsa screen
shots.>>

Sounds like a reasonable first draft of the approach, but I'd still suggest
some of the modifications I described above. The worksheet is particularly
important. Screenshots can be a two-edged sword, because even though they do
provide good context, they can also be so abundant they hide the procedural
steps. However you do this, make sure that you use lots of white space so
that the steps and cautions stand out from the background and from each
other; it's easy to inadvertently skip a line in long, tightly spaced lists
of instructions, and that could prove disastrous here.

<<Many of the Cautions and Warnings also refer to other chapters wherein I
expand on concepts or give advice on
handling and management.>>

You mentioned that some of the installers will just "bull through based on
past experience", which suggests that you need to clearly instruct them to
read and understand those chapters _before_ they begin the procedure. And
you need this warning before each procedure, not just in the introduction.
If the installation is time-sensitive, then you can't have readers hitting a
warning, suddenly realizing they don't know what to do about it, and having
to stop the installation so they can read the chapter.

<<Does it make sense to arbitrarily break a 23-action list into two, three,
or four numbered lists, just to avoid item numbers larger than 5 or 9 or
whatever?>>

Arbitrarily, no; intelligently, yes. Once you understand how readers will be
using the instructions (e.g., where they can pause to take a breath) and the
stages they pass through en route to completing the installation, you can
use that understanding to help you identify logical break points.

--Geoff Hart, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"The paperless office will arrive when the paperless toilet
arrives."--Matthew Stevens




Previous by Author: Can a technical writer be a Web designer?
Next by Author: How much is too much? (Take II)
Previous by Thread: Re: Can a technical writer be a Web designer?
Next by Thread: Re: How much is too much?


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

Sponsored Ads


Sponsored Ads