Developing a troubleshooting guide?

Subject: Developing a troubleshooting guide?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, Glen Blair <glen -dot- blair -at- gmail -dot- com>
Date: Tue, 07 Mar 2006 15:47:45 -0500

Glen Blair reports: <<One of the newer machines has caused some problems for our customers. A malfunctioning machine typically exhibits one of five or six general symptoms, but the cause of the same symptom can differ from machine to machine. Diagnosing the problem is often complex and regularly requires our field service engineers and customer support engineers (manning the phones) to refer customers directly to engineers working in research and development.>>

One note before beginning: The troubleshooting procedures should not just be used to solve customer problems; they should also become a resource for designers, who may be able to detect recurring themes and use them to identify and solve design flaws in the product. That may offer a larger potential payback than simply creating a troubleshooting guide.

Start with the recognition that you're trying to accomplish at least two things. First, you may want users to be able to diagnose or at least narrow-down problems before they call so as to minimize the time they spend on the phones with support staff. Second, you may want to come up with a tool that helps the support staff home in on a problem more quickly than might otherwise be the case, and provide proven (or at least "most likely") solutions without having to reinvent the wheel each time.

Both suggest that your first step should be to work with the field service and customer support people. An ideal, if somewhat chaotic, solution might be to gather a bunch of them together in one place for a joint meeting in which they identify the most common or serious problems (brainstorming) then discuss their problem-solving approaches. Paying attention to how they attack problems will reveal commonalities and differences in the approach; the advantage of getting them together in one place is that one person's comment may inspire someone else to remember something they might otherwise forget. It also lets you watch them discuss, attack, and defend the various approaches--and hopefully reach consensus on a smaller number of "best practices".

If you can't gather everyone together simultaneously, try to get at least one field person and one developer together; the former provides the reality check, and the latter provides the theoretical knowledge, and you can't solve the problem without both forms of knowledge. Once you've come up with an overview of the process, submit that to the other staff for feedback. Incorporate all the feedback to produce something semi-final that everyone can critique. Where you discover radical disagreements, you may not be able to achieve consensus, but may be able to determine situations in which each approach is most productive.

Remember to ask the users and your company's staff about the context for problem-solving. Users may be working in an environment where they need heavily plastified, highly legible printed flowcharts (i.e., no computer support available); your company's staff may work on a corporate network and find that a knowledge base works better. You may end up producing two or more products.

<<Much of the information I need is in the heads of individual technicians and engineers, and in "unofficial" emails exchanged by those emails (which I'm currently compiling).>>

Since this "tacit" knowledge is difficult to obtain by simply asking, consider using role-playing. For example, sit down with an engineer and say the following: "For the next few minutes, we'll pretend I'm a user and I just called you with a problem. 'The frammistat is not functioning.' What would you tell me to do?" To talk to field staff first so you understand what kind of problems arise and typical troubleshooting steps so that the role-playing exercise is credible; engineers hate it when you clearly don't know what you're talking about.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


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!.
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.


Developing a troubleshooting guide: From: Glen Blair

Previous by Author: An early contribution to the Friday file
Next by Author: Indexing Question?
Previous by Thread: Developing a troubleshooting guide
Next by Thread: Re: Developing a troubleshooting guide?

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

Sponsored Ads