RE: Developing a troubleshooting guide

Subject: RE: Developing a troubleshooting guide
From: "Jennifer Baldwin" <jbaldwin -at- desertdocs -dot- com>
To: "Glen Blair" <glen -dot- blair -at- gmail -dot- com>, "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 7 Mar 2006 15:01:36 -0700

Hi Glen,

I recently completed a documentation project for a similar problem. For that, I used an approach I adapted from the Harvard medical guide. I've been calling it the "symptom chart" approach.

In that book, there are charts for general categories of symptoms - headache, stomachache, etc. The charts are essentially flow diagrams that guide (through yes/no questions) the reader toward an informal diagnosis of the problem. Each question is in a box on the left side of the page, with a No arrow leading down to the next question and a Yes arrow leading to a follow-up question or to a "Taking Action" box. The right-most column is for extra information, typically leading to a cross-reference to where the reader can find more details in the guide.

What I love about the charts is that they provide a clear and visual entry point into the rest of the book. They simplify an otherwise complex process and quickly lead the reader to the information they really need.

With some alterations, I was able to apply this concept to my project. I was writing a book to help our business analysts to gather all of the requirements upfront when a customer calls with a change request. I categorized the type of customer requests they get and then broke each one down into a series of yes/no questions. Where appropriate, I listed out action items or identified points that would benefit from elaboration in the "More Information" column. I built the charts in Visio and pasted them into my Word doc.

So far, I've gotten some great feedback on it. As the BAs come across places in the charts that are incorrect or vague, it is relatively painless to correct them or add more yes/no questions and action items as needed.

Good luck!

Jennifer Baldwin

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.

Previous by Author: Annotating HTML - Edit
Next by Author: Stranger in a Strange Land - from TW to Sales
Previous by Thread: Re: Developing a troubleshooting guide?
Next by Thread: RE: Developing a troubleshooting guide

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

Sponsored Ads