Troubleshooting Guide

Thank you for downloading this template from The Good Docs Project! Before using the template, read this template guide for information about how to complete each section. Want to explore more templates? Check them out in our templates GitLab repository.

Overview

When should I include a troubleshooting guide?

Before you and your team decide to create a troubleshooting guide, consider asking yourselves the following questions:

• Is our product intuitive and error-free?
• Do we have the capacity to complete troubleshooting use cases?
• Do we have the bandwidth to maintain the troubleshooting guide and ensure its information remains relevant as the product evolves?

If you and your team answered yes to any of these questions, then go right ahead and create a troubleshooting guide.

Who typically writes a troubleshooting guide?

• Technical writers
• Subject matter experts (SME), a group of people who are highly knowledgeable in a specific aspect of the software or product
• Developers
• Customer support workers

Where is a troubleshooting guide stored?

This document is typically in a knowledge management system for employees and customers for organizational purposes.

Before you start

Before you start creating your troubleshooting guide, ensure that you have:

• Tested your solution on all platforms to see if it works

• Addressed the scenarios the user might be in before they read the guide.

• Images of code and or error messages. Note: Images can be difficult to maintain and can't be copied and pasted to a document, so it's best to take screenshots of relevant parts of the product and avoid using them if the text sufficiently describes the steps.

• Links to other resources that can help solve the problem

• Symptoms of the problem

• Solution of the problem

About the Introduction section

This section should help users understand within a few seconds whether they are reading the right document. Here, you want to describe the problem that users are having. A good example would be, "This article will help you resolve the slow response that often occurs when you turn on your Mac computer".

It's best to place this section at the beginning of your guide so users can get an idea of what they are going to read.

About the symptoms section

This section should describe the signs that end users should look out for in the problem you are describing. Describe the problem in bullet points to make it easier for users to understand what they should look out for if they experience the problem. More often than not, people are looking for solutions to a specific problem, so we recommend that you put this section after the introduction, describe each symptom as a question via bullet points, and link them to the corresponding issue.

About the solutions section

For this section, it is best to write the solution(s) in numbered steps. The user will be looking at the instructions while trying to solve the issue, so using this approach would help the person know which number to go back to and avoid missing a step. Additionally, write terms that describe parts of the software in bold to help users understand which part they should use in the step.

Best practices

• KISS( Keep It Short & Simple): Use short and simple explanations. They will make it easier for users to understand how to solve the problems.
• Use images: They provide a visual representation of the instructions needed to achieve the task. Note: Images can be difficult to maintain, so it's best to only screenshot the relevant parts of the product. Also, avoid using images if the text sufficiently describes the steps.
• Use meaningful headings: Your users will read your guide from top to bottom or sometimes skip to certain sections (depending on the guide's topic), so the headings will let them know exactly what the section is discussing.