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.
*************************
I am starting a new troubleshooting section for an existing manual, and I am
seeking advice on how to format these things. I can divide most of the
information into "Message/Possible Problem/Solution," but I am open to other
ideas on how to organize this information. Can anyone share any comments or
examples of formats (tables, lists, etc.) that worked well?
*************************
The most successful troubleshooting sections in my experience where the
"fault tables" in Minuteman III (ICBM) documentation. Essentially, a fault
table is a series of cells. Within each cell is the entering argument (a
problem or an action taken to solve a problem) and a series of outcomes or
suggested actions. The outcomes or actions may become entering arguments
to other cells, creating a "branch" structure that ends in either a
solution or the catch-all "Call Job Control" (which means you can't solve
it from the capsule and need help from maintenance).
To give an over-simplified example: Say the problem is "printer does not
print." That becomes the entering argument for a cell, which may suggest:
"Check power light; ref 3-3" In cell 3-3 (the "Check Power Light" cell) we
may find: "If light is off, turn power switch on; ref 3-4." In cell 3-4 we
may find: "Power light comes on, but printer will not print; ref 3-5." In
cell 3-5, (The "Power on, printer won't print" cell") we find, among other
suggestions, "Check printer cable connection." And so on. It's early in
the morning, I haven't seen one of these since 1985, so this may not be a
stellar explanation of the concept, but it's the best I can do at the
moment.
Anyway, it's main advantage is that it allows you to handle a wide variety
of problems in a structured way, and you only have to write stuff once
(several branches may use the "Power on, printer won't print" cell, for
example). It would be great implemented in a hypertext environment like
WinHelp. The main disadvantages are that it's hell to maintain, since
it's constantly impacted by system changes, and if a user gets off track
(makes a bad choice among suggested next steps in one of the cells) it's
tough for them to get back on the right track.
Hope this helps.
Skoal,
Doug "Multiply Life by the power of Two."
ENGSTROMDD -at- phibred -dot- com
--The Indigo Girls
***********************************************************************
The preceding opinions and positions are mine alone, and are only
coincidentally related to those of Pioneer Hi-Bred International, Inc.
***********************************************************************
