• EnglishEspañol日本語한국어Português
  • Inicia sesiónComenzar ahora

Troubleshooting docs guide

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.

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.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.