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.
Amy is looking for opinions on where to place troubleshooting sections in
user guides.
Amy, I'm going to be adding troubleshooting sections in the next release of
my manual, and I've been thinking about the same issue. I've opted to
include a *short* troubleshooting section (3-4 pages only) at the end of
each chapter because each chapter describes a different piece of equipment.
I document telecommunications hardware and software, and am going to place a
troubleshooting section behind the installation section for each piece of
equipment and behind the "turn up" section (i.e., I've wired my system
correctly, why won't it work?). I decided against an appendix at the end of
the doc because many users will not be using all of the equipment described
in the manual -- they may only be using equipment in chapters 1, 2, and 5 --
so I wanted the troubleshooting sections to be placed so that (a) the user
wouldn't need to flip back and forth from instructions to troubleshooting,
and (b) so that the user won't have to wade through unnecessary information
(why would they need to know troubleshooting information on equipment they
don't even have?). This is just what works in my case; it certainly won't be
the case universally. And yes, I'll be including these sections along with
all others in the TOC. And if a user needs further troubleshooting advice,
we always have field techs available to talk to them or go on site; that's
why I'm doing individual troubleshooting sections to hit the high points
rather than a separate troubleshooting guide.
Hope this helps,
Catheryn Mason, Technical Writer
Infinitec Networks
Tulsa, Oklahoma
(918) 481-5300 x280
fax (918) 877-4007
Winner, 1999 IABC Bronze Quill Award of Excellence for Technical Writing
Winner, 2000 IABC Award of Merit for Technical Writing
