diff --git a/docs.json b/docs.json
index af1132fe7..faeefb985 100644
--- a/docs.json
+++ b/docs.json
@@ -310,6 +310,7 @@
"guides/navigation",
"guides/seo",
"guides/style-and-tone",
+ "guides/troubleshooting-pages",
"guides/understand-your-audience"
]
},
diff --git a/guides/troubleshooting-pages.mdx b/guides/troubleshooting-pages.mdx
new file mode 100644
index 000000000..6d7d6bbab
--- /dev/null
+++ b/guides/troubleshooting-pages.mdx
@@ -0,0 +1,125 @@
+---
+title: "Troubleshooting pages"
+description: "Write troubleshooting content that helps users resolve issues quickly."
+keywords: ["troubleshooting", "errors", "debugging", "FAQ", "problem-solving", "support"]
+---
+
+
+ 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
+
+```mdx
+## 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.
+
+```mdx
+{/* 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.
+
+
+ Make sure your configuration is correct.
+
+
+
+### Group related issues
+
+If you have many troubleshooting entries, organize them by category (installation, authentication, deployment) rather than listing them in a single flat list.
+
+### Link to relevant documentation
+
+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:
+
+| Approach | When to use |
+|:---------|:------------|
+| **Section on an existing page** | One or two common issues tied to a specific feature |
+| **Dedicated troubleshooting page** | Five 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](/agent/workflows) to periodically audit your troubleshooting pages and flag entries that reference outdated versions or deprecated features.
+
+
+## Related pages
+
+
+
+ Choose the right content type for your documentation goals.
+
+
+ Use data and metrics to improve documentation.
+
+
+ Write effective documentation with consistent style.
+
+
+ Copy and modify templates for each content type.
+
+