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

[Kevin McLauchlan <KMcLauchlan -at- chrysalis-its -dot- com>]

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