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.
Paul wondered: <<I am tempted to place my nascent Troubleshooting
section into my release notes, which now have these sections: - new
features - Changes - closed issues - known issues Is there any real
reason to keep a Troubleshooting section at the end of my main admin
guide?>>
Interesting question. The problem with release notes is that not a lot
of people read them. We do, for sure, but we're Geeks, and not
necessarily representative of the larger world. Indeed, RTFM was
invented because people don't even read the main printed docs, let
alone release notes. <g>
The advantage of placing troubleshooting information in the release
notes is that much of it will be tied directly to the instructions and
procedures that produce problems. I've been a long-term advocate of
placing troubleshooting information directly in the steps that we know
are most likely to cause problems*--in effect, to divide such steps
into two parts, namely "here's what you should do" and "here's how
people routinely screw up this step and how you can tell whether you
succeeded or whether moving on to the next step will only add to the
mess".
* Of course, the real fix is to build a solution into the software. For
example, I just told a client that rather than specifying what language
settings users should select in the Windows control panels (failure to
do so causes significant problems), they should do two things: offer to
make this change for the user during software installation, and write a
tiny routine that runs during the launch of the software and displays
the necessary advice (i.e., "you've got the wrong settings, dude; we
won't allow this program to run until you make the following
changes...") Why leave to chance something you can automate for the
user? For that matter, why not test whether the user created a known
problem after each step, and if so, pop up a note telling them how to
fix it?
Nonetheless, it's traditional to place troubleshooting information at
the end of the main manual, in its own section, and it's rarely a good
idea to fight too hard against tradition. For example, there's no
reason other than tradition why we put indexes at the backs of books.
Why not put them up front with the table of contents (TOC), since both
are points of entrye into the larger work? Or use the (French?)
approach of putting the TOC at the back of the book with the index?
In any event, that's a digression; the real point is that you can do
both: include the relevant information in your release notes for those
who read them and need help troubleshooting the installation, then
provide that information plus any other troubleshooting advice in the
main docs, where everyone expects to find it.
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today!. http://www.webworks.com/techwr-l
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at http://www.DocToHelp.com/TechwrlList
