Our troubleshooting docs have these main sections: problem, solution, and (optionally) cause. Otherwise, a troubleshooting doc uses the basic doc template
Problem
Generally, this is the who, what, when, and where of the troubleshooting doc.
- Provide a clear, concise description of the problem the user is trying to solve.
- Include steps for reproduction, symptoms, and other key points when applicable.
- Re-state the problem in different ways if needed, to ensure customers can find this doc via Google.
If the problem text is very short, you can include the cause text here.
Solution
Generally, this is the how of the troubleshooting doc. Provide an ordered list of steps to guide users through the solution.
If there are multiple causes and solutions, consider creating a standard, basic page doc rather than using the troubleshooting template. Consider the best approach to help the reader, and discuss your reasoning with your peer editor.
If the issue you are documenting is more of a known issue (FYI in nature), or if it doesn't solve the issue:
Incorporate the information into other relevant docs. Do not refer to it as a known issue.
OR
Create a troubleshooting doc that describes the problem and cause. Do not include a solution. Also, include any statements promising that the issue will be fixed in a future release.
Cause
Generally, this is the why of the troubleshooting doc, and is optional. The Cause section is particularly useful when the product works in an unintuitive way.
Provide background information or context that gives the user additional insight into the problem. If the problem and the cause text are both very short, you can include the cause in the Problem section.
Related info
In general, leave blank. The standard For more help footer block will appear automatically when published. If necessary, use this section to link to other, related docs if it does not make sense to refer to them within the context of other information in the troubleshooting doc itself.