TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
I use an Information Mapping approach that seems
to work well with my adoring audience of Field
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
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
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
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
5. Step - Action Table Row
With this method, I still continuously number the steps,
and the steps in table form stand out on the page as
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
'Nuff on this. Hangin' the ol' keyboard back on the wall.
Dick Dimock Artfully Senior Technical Writer,
Information Developer, Information
Engineer, Information Analyst,
Technical Documentation Specialist
Senior Member Technical Staff,
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!
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.....