Skip to main content
This page explains how to structure troubleshooting content so users can diagnose and fix problems without contacting support.
Well-written troubleshooting pages reduce support tickets and improve user satisfaction. They work best when they’re scannable, specific, and solution-oriented.

​
When to write a troubleshooting page

Not every issue needs a dedicated troubleshooting section. Add troubleshooting content when:
  • Support sees repeated questions about the same issue
  • Error messages are unclear and users need additional context to resolve them
  • Setup or configuration involves steps where users commonly get stuck
  • Multiple causes can produce the same symptom

​
Structure each issue consistently

Use a repeatable format so users can quickly scan for their problem. Each issue should include:
  1. Symptom — what the user sees (error message, unexpected behavior)
  2. Cause — why it happens
  3. Solution — how to fix it
Lead with the symptom, not the cause. Users search for what they’re experiencing, not why it’s happening.

​
Example structure

## Error: "Authentication failed"

You see this error when your API key is invalid or expired.

**To fix this:**

1. Go to your dashboard and generate a new API key.
2. Replace the old key in your configuration file.
3. Restart the application.

​
Writing tips

​
Use the exact error message as the heading

Users often copy-paste error messages into search. Matching the exact text improves discoverability. 
{/* Good */}
## Error: "ECONNREFUSED 127.0.0.1:3000"

{/* Avoid */}
## Connection issues

​
Keep solutions actionable

Every troubleshooting entry should end with a concrete action. Avoid vague guidance like “check your configuration.” Instead, tell users exactly what to check and what to change.
Open config.yaml and verify that the port value matches the port your server is running on.
If you have many troubleshooting entries, organize them by category (installation, authentication, deployment) rather than listing them in a single flat list. After the solution, link to the related setup or configuration page so users can understand the broader context.

​
Include environment details when relevant

Some issues are specific to an operating system, language version, or deployment environment. Call this out so users can skip entries that don’t apply to them.

​
Page-level vs. dedicated troubleshooting

You have two options for where to put troubleshooting content:
ApproachWhen to use
Section on an existing pageOne or two common issues tied to a specific feature
Dedicated troubleshooting pageFive or more issues, or issues that span multiple features
For feature-specific pages, add a “Troubleshooting” section at the bottom. For broader issues, create a standalone page.

​
Keep troubleshooting content current

Troubleshooting pages go stale faster than other documentation. Build a review habit:
  • Monitor support channels for new issues that should be documented
  • Remove entries when bugs are fixed or errors are eliminated
  • Update solutions when product changes affect the fix
Use a workflow to periodically audit your troubleshooting pages and flag entries that reference outdated versions or deprecated features.

Content types

Choose the right content type for your documentation goals.

Improve your docs

Use data and metrics to improve documentation.

Style and tone

Write effective documentation with consistent style.

Content templates

Copy and modify templates for each content type.