How much is too much? (Long, as usual)

Subject: How much is too much? (Long, as usual)
From: Kevin McLauchlan <KMcLauchlan -at- chrysalis-its -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Sun, 13 Feb 2000 18:27:47 -0500

G'day all.

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?

I've seen opinions -- some stated rather dogmatically,
but hey, if you're going to have an opinion, why not
hold it strongly -- on how many steps a procedure should
be allowed to contain. I'm running into the problem now.

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.

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

OK, it's like this.

1) 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.

You commence the overall procedure from a untility on
your computer, where you make some choices, each of
which requires a bit of thought, depending on how
much experience you have with this stuff... almost
no-one HAS any experience with it. Then you are
referred to a connected, handheld device, that
prompts you through a bunch of actions and choices,
each of which needs some explanation, and most of
which (I think) need some stern warnings and cautions.
Then, you come back to the computer screen to finish
up. There's a global timeout on the whole operation,
and there are individual timeouts one most of the
actions that you perform with the handheld device.
The timeouts are security-related. The intervals
aren't so brief that fumble-fingers will ruin your
day, but they aren't long enough that you can go
for coffee between steps.

2) 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.

3) 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.

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

5) Our product is a hardware-based enhancement to other
people's (companies') applications, and in the field
is usually implemented by consultants or in-house
"experts" who DO have knowledge in the field --
normally at a less um, ah, strenuous level -- and
who are likely to bull ahead on the basis of
previously-valid assumptions. That is, their company
has bought our product because they recognize (or the
marketplace has TOLD them of) a need for far more
rigorous security than they've been using, and they've
heard that -- for good reasons (that they may not
really understand) -- we pretty well own the
market-space for what we do.

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.

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

In the Intro (before chapter 1) I come right out and
tell the reader to review the instructional chapters
before attacking the active stuff -- "Your livelihood
depends on getting this right!"
But we all know that nobody ever reads the intro, so
almost the first thing I say in the action chapter is:
"Read and understand Chapters X and Y and Z, then
formalize your security policy and walk through at least
one "dry run" before you ever pick up the hardware. You
must consider all the variables and carefully think
through the policies and procedures you will adopt. For
many of these operations, errors can be costly and
there is no 'Undo' option." ... or words to that effect.

What do you folks think? Does it make sense to keep
the numbered steps uncluttered by explanation, cautions
and "things you really oughta consider, right about now",
just for the sake of keeping it clean?

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?
If the reader stops anywhere before the second-last
numbered step, they'll likely hit a timeout and
have to go back almost to the beginning.

Is this a forest I'm staring at? Or is it just a
bunch of trees? :-)
No, wait.... it's a deadline!

Thanks for any words of wisdom.

/k




Previous by Author: RE: Screen Capture Utility for Solaris
Next by Author: Under the hood (was RE: How much is too much?
Previous by Thread: Re: Can a Technical Writer be a Web Designer
Next by Thread: Re: How much is too much? (Long, as usual)


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

Sponsored Ads


Sponsored Ads