Troubleshooting guides

From TechWriter Wiki

Jump to: navigation, search

Troubleshooting guides are designed to help users identify and resolve problems they are having. This includes messages and codes manuals. Bear in mind that users will only refer to troubleshooting guides when they have a problem, and often as a last resort. They are therefore likely to be stressed, in a hurry, and not particularly well-disposed to the product. The troubleshooting guide therefore needs to be direct and to the point. It should also be as self-contained as possible, not requiring users to go off and check other information elsewhere.

Troubleshooting guides are best structured as `This has happened': how do I fix it?". A secondary consideration would be "What caused it, and how do I stop it happening again?". Troubleshooting guides therefore often consist of a series of short statements or scenarios describing potential problems, followed by a description of how to resolve the problem. The scenarios should be very short (ideally no more than a sentence) as the user will need to scan through these to quickly locate the scenario that matches their predicament. They should also focus on what the user sees, rather than what they did to get to that position.

Another common format of troubleshooting guides is a decision tree, or symptom flowchart, where the user is led through a series of questions about what they are experiencing, until they reach their exact scenario. Often, these start with a statement of the problem. For example:

  • Is anything being printed:
    • Yes: Is the print legible?
      • Yes: Something
      • No: Something
    • No: Is the printer switched on?
      • Yes: Is the printer connected to the network?
        • Yes: Something
        • No: Something

Consider the relative seriousness of the error. This may be coded into any error message, and users will normally understand the difference between information, warning, and error messages - although you should always provide an explanation of these at the front of the guide.

Consider also that there may be different responses to an error messages for different audiences - for example, the user response and the system administrator (operator)response may be different. In such cases, you should clearly identify the person (role) who is required to carry out each response.

Personal tools