Troubleshooting content is provided as an aid to solve problems. The goal of troubleshooting content is to identify the root cause of a feature or functionality not working as expected and how to resolve the problem.
Let us look at what could be included in Troubleshooting content to make it helpful for our users.
The first step in resolving a problem is to understand the problem. One can understand the problem by describing the problem well. You may start with a brief heading but it should quickly follow with a detailed description of the problem. When describing the problem, try to answers following questions to make it more descriptive:
Describe what is causing the problem. It might sound like we are exposing our faults but when something is not working as expected, it is only fair to explain what went wrong. This provides user a context and clarity on root of the issue and doesn’t leave them wondering if they messed up somewhere. There had been cases that I have been asked to document that there was quality issue meaning that the developer missed to include a certain piece of code for the feature to behave unexpectedly. However, if there is none, you may just leave out this section.
Provide the steps required to fix the problem. Do not hesitate in including details or reference to details help topics for additional context. If there are multiple workarounds, include them. You may use phrase such as, “Consider the following possible solutions” to get started with multiple options for users. This is the goal for all the troubleshooting content – to help the users resolve the issues on their own.
Troubleshooting content should be an integral part of any help system. It makes the users more independent, reduces support cost for users and support calls for product owners, and provides a better experience to all involved with the product.