Long procedures, Artfully done

["Dimock, Dick" <red -at- ELSEGUNDOCA -dot- NCR -dot- COM>]

Well, ol' Artfully Senior has to de-cloak and add his
bit on *Lllloooonnnnggg Procedures*.

One of my ongoing manuals is a complete step-by-
step procedure for installing a very large computer
system (50 cabinets and more) and our complex
database software.

I use an Information Mapping approach that seems
to work well with my adoring audience of Field
Engineers.

The book is in chapters, each chapter covering a
"chunk" of the overall procedure. The chapters are
sequenced in chronological order.

Each chapter contains a series of numbered "Tasks".
The first page of each chapter has a table showing the
individual Tasks in sequence.

Most Tasks break down directly into steps in a
Step-Action table. I give the action, the UNIX command,
the UNIX response, etc., in sequential steps. Tasks
get a Heading Level 1 heading, and start on a new
page. Even the 1/4 page Tasks get their own page.
(Nothin' like White Space to save your rear end later,
after the TOC is printed.)

Many of the Tasks break down into several Sub Task
sequences, which get Heading Level 2 headers.
I re-start the step numbering for each Sub-Task
Step-Action table.

Often I must insert Knowledge Blocks into the stream
of Procedures. These paragraphs explain:

 -    Choices coming up in the procedure
 -    Where to get more info
 -    Or give examples.

Usually this text goes at the beginning
of the Task or Sub-Task. However, comma, it can
become challenging.

Often, I sneak little "Knowledge Bites"  B-(      into the
step itself: a short sentence or so doesn't hurt the
procedure flow.  But paragraphs or whole pages
can distract, and usually belong outside as Knowledge
Bites.

One of my recent wrinkles is to intersperse text Knowledge
Blocks directly among the steps of the procedure:

3.  Step - Action Table  Row

Paragraphs of Knowledge and Examples

4.  Step - Action Table Row

'Nuther buncha prose. Usually using Heading Level 3s
and 4s.

5.  Step - Action Table Row

Etc.

With this method, I still continuously number the steps,
and the steps in table form stand out on the page as
guides.

The book is very dynamic. New chapters are added,
existing chapters get moved about as technical changes
require, and I am frequently adding new material as
information comes back from the Field Engineers. The
layout expands or contracts very easily.

The Information Mapping approach seems to handle
the Book-sized Procedure.

No, I do not consider I.M. to be restricting.  I can always
break loose and *Create* if I want. And after a binge of
*Create*, I find I have created a decently Mapped procedure.
Info Mapping is just common sense, packaged and
sold.

'Nuff on this. Hangin' the ol' keyboard back on the wall.

Best Regards

Dick Dimock    Artfully Senior Technical Writer,
          Information Developer, Information
          Engineer, Information Analyst,
          Technical Documentation Specialist
          Senior Member Technical Staff,
          Engineering Writer........
          and many other titles over the years,
          now comfortably ensconced at

NCR Corp. Poised for the Leap of Faith, to fly
          free and unencumbered by AT&T,
          eager to take on the challenges of
          business in the 21st Century And Beyond!

          Well, eager or not, here we go!
          In

El Segundo, CA The Faire Citie by the Sea, where this
          Halloween we did NOT cover the water
          tower with a ghostly sheet. The Citie has
          added many fresh murals on building
          walls, that depict the history of the Chevron
          refinery and the town that grew around it.
          Very fresh, colorful, nicely done. I have
          *never* seen graffiti in this town. Clean air,
          too,   ....upwind of the refinery.....