Web Writing That Works!

           A Project of
           The Communication Circle

Guidelines Rants Patterns Poems Services Classes Press Blog Resources About Us Site Map

HomeRants > How to write FAQs > Create troubleshooting sections





Big trouble

Create troubleshooting sections

A troubleshooting section is not a conventional FAQ. Instead of Q&A, you have a three-part structure: (1) symptom, (2) diagnosis, and (3) solution. Offer troubleshooting sections as a supplement to your FAQ.


Start with the symptom (not a question), as described by the user (not an engineer).

Good: "I downloaded the software, but it won't start."
Bad: "Difficulty in launch."

Sum up the problem in terms that your guests would really use, so they can recognize their situation.

When most people get in trouble, they describe their problem to themselves, and they use those words when they call or e-mail customer support. If you want people to recognize that you are offering a solution, use their words in the heading.

Related article

Writing in a genre (Full chapter from Hot Text, in PDF, 770K, or about 13 minutes at 56K)

Hurray for FAQs (PricePoint)


Give your diagnosis of what may be going wrong, if you have any idea.

Identify the diagnosis with a subhead, setting it off, so the anxious user can skip this section, and the curious can learn to perform this analysis.


Break out the solution, too, with its own subhead.

Usually, this section requires numbered steps, if there is a concrete sequence of actions to perform.

But sometimes you're offering a handful of options, in a bulleted list. Only use numbers if the user must perform the steps in order.

Big trouble

If you face a really complicated problem, use a branching diagnostic approach.

In response to the problem, ask a question, and offer all possible answers as links.

When the user clicks one, offer the next logical question, and the next, and so on, until you are pretty sure you know what the problem is.

Then give the specific fix for that problem.

Branching diagnostics like this are wonderfully helpful.

Look at the way Windows Help handles printing problems. The branching means the user is following his or her own path, unaware of all the other possibilities, able to maintain focus.  


The task is to be aware and sensitive to your customers' expectations and level of upset.
-Ron Zemke and Tom Connellan, e-Service

Now how do I get out of this?


Home | Guidelines | Rants | Patterns | Poems | Services | Classes | Press | Blog |
Resources | About Us | Site Map

Web Writing that Works!
  2002-2004 Jonathan and Lisa Price
The Communication Circle
Discuss at HotText@yahoogroups.com
Email us directly at ThePrices@ThePrices.com
Order Hot Text (the book) from Amazon