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'm working on a hardware service manual that will include a Troubleshooting
>section. I am interested to learn how others organize this section. I will be
>listing the information in a table format with the headings similar to
>"Problem," "Cause," and "Actions to take."
>My question is how would be the best way to list the problems. Alphabetize
them?
>List by major section? For example a car might have problem sections for
engine,
>fuel system, etc.
>Opinions anyone?
>Elizabeth Huth
>elizabeth_huth -at- gilbarco -dot- com
Elizabeth,
I would organize it by symptoms - whatever tells the user that a problem
exists. This may be LEDs, audible sounds, error messages, general lack of
functioning (e.g., in clearly defined functional terms, line "when you press
X, nothing happens"), etc.
The point of the troubleshooting section is to (a) locate the problem -
therefore you can't reasonably sort the table by location of the problem
because the user may not know the source/cause (I'm referring to your list
of "engine," "fuel system," etc.); and (b) give step-by-step instructions
for solving the problem.
I used the same type of table you suggest with Problem (symptom!!! or how
the user knows there is a problem), Cause and Action.
If the symptom is an error message, I would alphabetize them. I usually put
Error Messages in a separate appendix, because users know if this is what
they need to look up. Troubleshooting I leave to less apparent problems.
I also make the first step an overview of the process, as a means of leading
the reader directly to the correct area of the tables.
The last step of each troubleshooting procedure should be to call the
company tech support for assistance. Never lead the reader to a dead end.
I also use a two-page spread - left side is a graphic of the system or
subsystem in question, with numbered call-outs referring to the step-by-step
text on the right page for solving the problem. This helps the user to
identify the system or subsystem "responsible" for the particular type of
symptom, and work through a logical thought process for troubleshooting
problems with it. It is true that the primary purpose of troubleshooting is
to provide an easy-to-use guide to lead a user through resolution; the
secondary purpose is to help users to develop logical thought processes
about the operation of the system so they don't have to depend on the guide.
I hope this helps. Sounds like you're on the right track. Good luck!
Betsy Maaks
****************************************************************
Betsy Maaks + Frame Technology Corp.
312-266-3208 + Advanced Products
bmaaks -at- frame -dot- com + 441 W. Huron Street
+ Chicago, IL 60610
