Troubleshooting Guide Template

I need to write a Troubleshooting Guide. Act as an expert technical writer and draft one for me.

Use this structure, keeping each section clear, concise, and genuinely useful to the reader:

1. Symptom or problem statement
2. Who and what it affects
3. Likely causes at a glance
4. Diagnostic path
5. Solutions by cause
6. Still stuck? Escalation and contact
7. Related issues and articles

Before you begin, ask me for the details you need: the product, team, or audience this is for, and anything specific I should include. Then write the full Troubleshooting Guide in clean, well-formatted Markdown.

Write a Troubleshooting Guide using the structure below. Keep each section clear, concise, and genuinely useful to the reader.

Structure:
1. Symptom or problem statement
2. Who and what it affects
3. Likely causes at a glance
4. Diagnostic path
5. Solutions by cause
6. Still stuck? Escalation and contact
7. Related issues and articles

Use rich formatting so it reads well in a knowledge base:
- Clear headings and subheadings for each section.
- Callout boxes for asides: a Tip callout for advice, a Note callout for helpful context, and an Important callout for anything a reader must not miss.
- Tables for structured or comparison content.
- Numbered lists for sequential steps and bulleted lists for options.
- Bold for key terms and any values people must not get wrong.

## The troubleshooting guide template

### 1. Symptom or problem statement

Describe the problem exactly as the reader experiences it, in their words, not yours. Lead with what they see ("The export fails with a spinning loader that never finishes"), because the symptom is what they will type into search.

### 2. Who and what it affects

Note who runs into this and under what conditions: a plan tier, a browser, a role, a specific setting. Ruling readers in or out early saves them from following a path that was never going to apply to them.

### 3. Likely causes at a glance

Before the detailed steps, give a quick matrix that maps each symptom to its most common cause and the fix. Many readers will self-serve from this table alone and never need to scroll.

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Export never finishes | File too large for the browser to process | Filter the date range and retry |
| "Permission denied" error | Account lacks admin access | Ask an admin to grant the role |
| Nothing happens on click | Browser extension blocking the action | TODO |

### 4. Diagnostic path

The heart of the guide. Give an ordered set of checks that narrow the problem down, starting with the most common and quickest to rule out. One check per step, and after each, tell the reader what the result means and where to go next.

1. **Check the most common cause first.** State the check, then branch clearly ("If you see X, go to Fix A. If not, continue to step 2").
2. **Rule out the next cause.** Keep each step to a single check with an unambiguous outcome.
3. **Narrow to the specific fix.** By the end of the path, the reader should land on exactly one of the solutions below.

### 5. Solutions by cause

For each cause the diagnostic path can land on, give the fix as clear numbered steps. Keep the cause and its solution together so the reader who identified their cause can act without hunting.

- **Cause A.** The fix, step by step, with the expected result once it works.
- **Cause B.** The fix, step by step, plus how to confirm the problem is gone.
- **Cause C.** The fix, and what to do if it only partly resolves the issue.

### 6. Still stuck? Escalation and contact

When none of the fixes work, tell the reader exactly what to do next: who to contact, through which channel, and what details to include (the error text, steps to reproduce, screenshots). A clear escalation path turns a dead end into a handoff.

### 7. Related issues and articles

Link to adjacent problems that produce a similar symptom, plus the how-to guide for the task the reader was trying to complete. Cross-linking keeps each guide focused on one issue and helps a reader who is in the wrong article find the right one.

The troubleshooting guide template

Copy this structure into a new article and replace the guidance in each section with the specifics of your issue. Keep the headings; they are what make one troubleshooting guide feel like the next, and they are what a frustrated reader scans for fast.

1. Symptom or problem statement

Describe the problem exactly as the reader experiences it, in their words, not yours. Lead with what they see (“The export fails with a spinning loader that never finishes”), because the symptom is what they will type into search.

2. Who and what it affects

Note who runs into this and under what conditions: a plan tier, a browser, a role, a specific setting. Ruling readers in or out early saves them from following a path that was never going to apply to them.

3. Likely causes at a glance

Before the detailed steps, give a quick matrix that maps each symptom to its most common cause and the fix. Many readers will self-serve from this table alone and never need to scroll.

4. Diagnostic path

The heart of the guide. Give an ordered set of checks that narrow the problem down, starting with the most common and quickest to rule out. One check per step, and after each, tell the reader what the result means and where to go next.

1. Check the most common cause first. State the check, then branch clearly (“If you see X, go to Fix A. If not, continue to step 2”).
2. Rule out the next cause. Keep each step to a single check with an unambiguous outcome.
3. Narrow to the specific fix. By the end of the path, the reader should land on exactly one of the solutions below.

5. Solutions by cause

For each cause the diagnostic path can land on, give the fix as clear numbered steps. Keep the cause and its solution together so the reader who identified their cause can act without hunting.

• Cause A. The fix, step by step, with the expected result once it works.
• Cause B. The fix, step by step, plus how to confirm the problem is gone.
• Cause C. The fix, and what to do if it only partly resolves the issue.

6. Still stuck? Escalation and contact

When none of the fixes work, tell the reader exactly what to do next: who to contact, through which channel, and what details to include (the error text, steps to reproduce, screenshots). A clear escalation path turns a dead end into a handoff.

7. Related issues and articles

Link to adjacent problems that produce a similar symptom, plus the how-to guide for the task the reader was trying to complete. Cross-linking keeps each guide focused on one issue and helps a reader who is in the wrong article find the right one.

How to fill in this troubleshooting guide template

A template only helps if the finished guide actually gets someone unstuck. A few habits make the difference:

• Name the symptom, not the cause. Readers search for what they see, not for the internal reason behind it. Lead with their words.
• Order causes by likelihood. Put the fix that resolves most cases first. Sending people down the rarest path first wastes the time they do not have.
• Keep the cause and fix together. Once a reader identifies their cause, the solution should be right there, not in a separate section they have to find.
• Give an honest escalation route. Some problems genuinely need a human, so make the handoff clear and tell the reader what to include so the next person can help fast.
• Update it when new causes appear. Troubleshooting content ages quickly as products change. Add the new cause the moment support sees it twice.

For the task the reader was originally trying to complete, link out to the matching how-to guide. A how-to guide shows the happy path; this guide catches them when that path breaks.