Add troubleshooting pages best practices guide

docs.json

@@ -310,6 +310,7 @@
                   "guides/navigation",
                   "guides/seo",
                   "guides/style-and-tone",
+                  "guides/troubleshooting-pages",
                   "guides/understand-your-audience"
                 ]
               },

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"]
+---
+
+<Tip>
+  This page explains how to structure troubleshooting content so users can diagnose and fix problems without contacting support.
+</Tip>
+
+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
+
+<Note>
+  Lead with the symptom, not the cause. Users search for what they're experiencing, not why it's happening.
+</Note>
+
+### 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.
+
+<Tabs>
+  <Tab title="Good">
+    Open `config.yaml` and verify that the `port` value matches the port your server is running on.
+  </Tab>
+  <Tab title="Avoid">
+    Make sure your configuration is correct.
+  </Tab>
+</Tabs>
+
+### 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
+
+<Tip>
+  Use a [workflow](/agent/workflows) to periodically audit your troubleshooting pages and flag entries that reference outdated versions or deprecated features.
+</Tip>
+
+## Related pages
+
+<CardGroup cols={2}>
+  <Card title="Content types" icon="folder-tree" href="/guides/content-types">
+    Choose the right content type for your documentation goals.
+  </Card>
+  <Card title="Improve your docs" icon="chart-line" href="/guides/improving-docs">
+    Use data and metrics to improve documentation.
+  </Card>
+  <Card title="Style and tone" icon="pen" href="/guides/style-and-tone">
+    Write effective documentation with consistent style.
+  </Card>
+  <Card title="Content templates" icon="file-code" href="/guides/content-templates">
+    Copy and modify templates for each content type.
+  </Card>
+</CardGroup>