Re: Need Troubleshooting advice

Subject: Re: Need Troubleshooting advice
From: Stephen Victor <svictor -at- HOUSTON -dot- GEOQUEST -dot- SLB -dot- COM>
Date: Fri, 23 May 1997 12:43:21 -0500

Matt Ion wrote:
> Troubleshooting guides, in my experience, are more to cover weaknesses
> in users' systems and knowledge. For example:
> Q: I installed the program and now it won't run.
> A: Is the computer turned on?
> Extreme example, but you get the idea. *Especially* in the PC world,
> there's an infinite variety of hardware and software combinations out
> there that are out of your control, but that may affect the proper
> operation of YOUR software. Troubleshooting guides, IMHO, should give
> basic information on tracking down the source of problems (which are
> presumably due to something BESIDES your software) and how to deal with
> them.

Well-written troubleshooting guides can be an invaluable source of
information for system administrators who are trying to diagnose
problems with their systems. A good troubleshooting guide can address
more than just basic problems (although there's nothing wrong with
writing guides for users who need very basic instructions like "Turn on
the computer").

Working with support people (very important) and developers, a technical
writer can produce guides that address real problems experienced by real
users. You're correct that there could be an infinite variety of
software/hardware configurations, but don't most software developers
have a limited set of *supported* configurations? Working within the
limits of supported configurations, it's possible to write
troubleshooting guides that are both complete and useful.

The original poster stated that management at her company was concernced
that a troubleshooting guide would reveal flaws. While that's one
extreme (and very unusual, in my experience) way of looking at such a
guide, the poster could present another way of viewing it: as an
important customer service. A troubleshooting guide, like other forms of
good documentation, can result in happier customers and fewer support


Stephen P. Victor Phone: (713) 513-2552
Technical Writer, Software Training Fax: (713) 513-2019
Schlumberger GeoQuest svictor -at- houston -dot- geoquest -dot- slb -dot- com
5599 San Felipe, Suite 1700
Houston, Texas 77056 USA

TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
Search the archives at or search and
browse the archives at

Previous by Author: Re: Temping: An alternative to agencies?
Next by Author: Re: Who has used FrameMaker or Frame+SGML to do single-source docs?
Previous by Thread: Re: Need Troubleshooting advice
Next by Thread: Re: Need Troubleshooting advice

What this post helpful? Share it with friends and colleagues:

Sponsored Ads