What Is a Troubleshooting Article?
A troubleshooting article helps a reader diagnose and resolve a problem. It is written from the reader's perspective: they have encountered an unexpected situation, error, or behavior and need to understand what is happening and how to fix it. See the Troubleshooting Articles section of the Five Core Content Types guide for how this type relates to the other four, and specifically how its symptom-first organization differs from a how-to article's goal-first organization; this article is the fuller treatment of that entry.
Troubleshooting articles are often the highest-traffic content in a knowledge base because they are triggered by real user pain. Well-written troubleshooting content directly reduces support volume.
When to write a troubleshooting article: when users encounter errors, unexpected behavior, failed tasks, or performance issues. Draw on support tickets, search queries, and article feedback to identify what to document — this is the troubleshooting-specific application of the "treat your support queue as a documentation backlog" guidance in the Documentation Lifecycle guide.
Structure
Title
Name the symptom or error the reader is experiencing. Titles should match how readers describe the problem in their own words.
- Users cannot log in after SSO configuration
- Articles not appearing in search results
- Import fails with "Invalid file format" error
For grouped troubleshooting articles (covering multiple issues in one section), use a category-level title: "Troubleshooting login issues."
Symptom description (1–2 sentences)
Describe the symptom in concrete, observable terms. What does the reader see? What error message, behavior, or missing result prompted them to open this article?
Example: "After configuring SSO, team members with existing accounts are redirected to an error page when attempting to log in using single sign-on."
Cause (where known)
Explain why the problem occurs. Keep this brief — one sentence to one short paragraph. If there are multiple possible causes, list them. If the cause is unknown, skip this section.
Readers find cause explanations helpful because they can often identify their own situation from the description and jump straight to the relevant fix.
Resolution
For a single cause, provide a numbered list of steps to resolve the issue, following the same step-writing rules as a how-to article — see the Writing How-To Articles and Writing Procedures guides for the mechanics (one action per step, imperative verbs, bolded UI elements, stated results).
For multiple possible causes, structure the resolution section with a heading per cause:
## Cause 1: [Description]
[Steps to resolve]
## Cause 2: [Description]
[Steps to resolve]
At the end of each resolution, state the expected outcome: "After completing these steps, existing users should be able to log in via SSO without errors."
If a resolution step involves an irreversible or risky action (clearing data, resetting a configuration, disconnecting an integration), flag it with a Warning callout per the Callouts guide, rather than stating it as a plain step — a reader troubleshooting under stress is exactly the reader least likely to notice an unflagged risk.
If the issue persists
Include a final section with escalation guidance: what the reader should do if none of the resolutions work. This typically means contacting support. Provide the information they will need to gather before they do: logs, error codes, screenshots, configuration details.
Related articles
End with links to the conceptual article explaining the underlying feature and the how-to article for the correct configuration or usage, where relevant — the same convention used in the Writing Conceptual Articles and Writing Reference Articles guides. A reader who hits an error is often one misconfiguration away from the correct how-to procedure, and linking there directly can prevent the same issue recurring.
Length
Troubleshooting articles are usually shorter than conceptual articles, focused tightly on one symptom and its resolutions — see the Depth Versus Breadth guidance in the Structuring a Knowledge Base guide. If an article is growing long because it covers several unrelated symptoms, split it into separate articles or a grouped troubleshooting section instead of one long article.
Template
[Title — symptom description]
[1–2 sentences describing what the reader observes]
## Cause
[Brief explanation of why this happens — omit if unknown]
## Resolution
### [Cause 1 if multiple, or omit heading for single cause]
1. [Step]
2. [Step]
3. [Step]
[Expected outcome after following the steps]
### [Cause 2 if multiple]
1. [Step]
2. [Step]
[Expected outcome]
## If the issue persists
[Contact support or escalation guidance, including what information to gather]
## Related articles
- [Conceptual article]
- [How-to article]
Writing Effective Troubleshooting Content
- Use the reader's language. Titles and symptom descriptions should use the exact error message text, the exact UI phrase, or the exact phrasing readers use in support tickets. This is what they will search for.
- Order resolutions by likelihood. Put the most common cause and quickest fix first.
- Be specific about preconditions. "This issue only occurs when two-factor authentication is enabled" saves the reader from trying a fix that does not apply to them.
- Confirm resolution explicitly. After the final step, always tell the reader what success looks like.
- Keep causes honest. If a problem is a known bug or limitation, say so. Readers trust documentation that is truthful about product shortcomings.
Grouping vs. Individual Articles
Troubleshooting content can be structured as individual articles (one issue per article) or as a grouped troubleshooting article (multiple issues in one article under separate headings). Use these guidelines:
- Individual articles are better for complex issues with multiple resolution paths, or issues that are very commonly searched independently.
- Grouped articles are better for a set of related minor issues that do not warrant individual articles, or when a feature category has several intermittent edge cases.
Tone
Calm, clear, and solution-focused. Readers arrive at troubleshooting articles frustrated. Your tone should reduce that frustration, not amplify it. Avoid language that assigns blame or implies user error ("If you configured this correctly..."). Focus entirely on what to do next.
Self-Audit Checklist
Before publishing, check the troubleshooting article against these questions:
- Does the title name the symptom using the reader's own language, including exact error text where relevant?
- Does the symptom description state concrete, observable details, not a vague summary?
- Is the cause explained briefly where known, and omitted (not guessed at) where unknown?
- Do resolution steps follow the same step-writing rules as a how-to article?
- Are irreversible or risky resolution steps flagged with a Warning callout?
- Does each resolution path end with a stated expected outcome?
- Is there an escalation section explaining what to gather before contacting support?
- Does the article link to the related conceptual and how-to articles?
- Is the article focused on one symptom, with unrelated issues split into separate or grouped articles instead?
- Is the tone calm and blame-free throughout?