What is a troubleshooting guide?

A document that helps a reader find the cause of a problem and fix it, organised by the symptoms they see. It differs from a how-to guide, which describes a task that goes well, and from a runbook, which is a procedure for operators who respond to an alert.

How is a troubleshooting guide different from a runbook?

A troubleshooting guide is written for users, customers or colleagues who hit a problem, and starts from what they see. A runbook is written for on-call engineers who respond to an alert, and starts from the alert. The same incident can have both.

What should I put at the top of a troubleshooting article?

The exact error text or the symptom in the title, the versions or environments it applies to, and one line saying whether this is your problem. Readers decide in seconds whether to keep reading.

How do I write a diagnosis flowchart?

Use yes or no questions that the reader can answer by looking at one place, and end each branch at a fix or at "contact support". A Mermaid flowchart is plain text, so it can be reviewed and changed like the rest of the page. Keep it to about ten nodes; if it grows, split the guide.

How often should a troubleshooting guide be reviewed?

After every release that changes the feature, and at least every six months. Add any ticket that the guide did not resolve as a new cause or a new known issue.

Troubleshooting Guide Template (Markdown)

A troubleshooting guide template in plain Markdown for a documentation writer or a support engineer. It is built around the symptom: the exact error text, a quick diagnosis, and then each cause with its fix and a way to check it. It ends with what to send to support if nothing worked. Copy it, download the .md file, or keep it with the product documentation.

Free to use, no attribution required (CC0).

Open in Folio demo

Troubleshooting: {{Symptom the reader sees}}


Applies to	{{Product, version or environment}}
Audience	{{User, admin or support engineer}}
Owner	{{Name or team}}
Source	{{Link to the code, pull request or ticket}}
Last reviewed	{{YYYY-MM-DD}} by {{Name}}
Next review	{{YYYY-MM-DD}}

Symptoms

Quote the exact error text and wording from real reports so that a search for it finds this page.

Error message: {{Exact text}}
What you see: {{The screen, behaviour or log line}}
When it happens: {{After an update, only for some accounts, on first start}}

Is this your problem?

{{Quick check 1: a version, a setting or a status page}}
{{Quick check 2}}

If a check fails, go straight to the fix it names. If all pass, continue.

Diagnosis

Edit the labels so the flowchart matches your product. End each branch at a fix or at "contact support".

flowchart TD
    A[Symptom appears] --> B{Is the service reachable?}
    B -- No --> C[Cause 1: connection]
    B -- Yes --> D{Is the account allowed?}
    D -- No --> E[Cause 2: permissions]
    D -- Yes --> F[Cause 3: configuration]
    C --> G[Fix 1]
    E --> H[Fix 2]
    F --> I[Contact support]

Cause 1. {{Most common cause}}

How to confirm: {{A check, a command or a log line}}

Fix:

{{Step}}
{{Step}}

{{command}}

Check that it worked: {{What the reader sees now}}

Cause 2. {{Next cause}}

How to confirm: {{...}}

Fix:

{{Step}}
{{Step}}

Check that it worked: {{...}}

Known issues

Issue	Workaround	Status
{{Description}}	{{Workaround}}	{{Link to the ticket or the fixed version}}

Still stuck?

Say when to stop and what makes help fast.

Contact {{support channel}} and include:

The exact error text or a screenshot
{{Version and environment}}
{{Logs or a request ID, with secrets removed}}
What you already tried from this page

{{How-to guide for the task that failed}}
{{Reference for the settings involved}}
{{Runbook, if operators respond to this}}

Review checklist

Tick before you ask for a review. Keep the list for the next reviewer or delete it when the page is published.

The symptoms use the exact wording from real tickets or logs
Someone reproduced the failure and followed the fix on a clean environment
Each cause has a way to confirm it and a way to check the fix
The flowchart ends every branch at a fix or at support
Logs and examples contain no secrets or customer data
The source link and the versions in the table are current
Owner, last reviewed and next review are filled in

Revision history

Date	Author	Change
{{YYYY-MM-DD}}	{{Name}}	First version

# Troubleshooting: {{Symptom the reader sees}}

| | |
|---|---|
| **Applies to** | {{Product, version or environment}} |
| **Audience** | {{User, admin or support engineer}} |
| **Owner** | {{Name or team}} |
| **Source** | {{Link to the code, pull request or ticket}} |
| **Last reviewed** | {{YYYY-MM-DD}} by {{Name}} |
| **Next review** | {{YYYY-MM-DD}} |

## Symptoms

*Quote the exact error text and wording from real reports so that a search for it finds this page.*

- **Error message:** `{{Exact text}}`
- **What you see:** {{The screen, behaviour or log line}}
- **When it happens:** {{After an update, only for some accounts, on first start}}

## Is this your problem?

- [ ] {{Quick check 1: a version, a setting or a status page}}
- [ ] {{Quick check 2}}

*If a check fails, go straight to the fix it names. If all pass, continue.*

## Diagnosis

*Edit the labels so the flowchart matches your product. End each branch at a fix or at "contact support".*

```mermaid
flowchart TD
    A[Symptom appears] --> B{Is the service reachable?}
    B -- No --> C[Cause 1: connection]
    B -- Yes --> D{Is the account allowed?}
    D -- No --> E[Cause 2: permissions]
    D -- Yes --> F[Cause 3: configuration]
    C --> G[Fix 1]
    E --> H[Fix 2]
    F --> I[Contact support]
```

## Cause 1. {{Most common cause}}

**How to confirm:** {{A check, a command or a log line}}

**Fix:**

1. {{Step}}
2. {{Step}}

```bash
{{command}}
```

**Check that it worked:** {{What the reader sees now}}

## Cause 2. {{Next cause}}

**How to confirm:** {{...}}

**Fix:**

1. {{Step}}
2. {{Step}}

**Check that it worked:** {{...}}

## Known issues

| Issue | Workaround | Status |
|---|---|---|
| {{Description}} | {{Workaround}} | {{Link to the ticket or the fixed version}} |

## Still stuck?

*Say when to stop and what makes help fast.*

Contact {{support channel}} and include:

- The exact error text or a screenshot
- {{Version and environment}}
- {{Logs or a request ID, with secrets removed}}
- What you already tried from this page

## Related pages

- {{How-to guide for the task that failed}}
- {{Reference for the settings involved}}
- {{Runbook, if operators respond to this}}

## Review checklist

*Tick before you ask for a review. Keep the list for the next reviewer or delete it when the page is published.*

- [ ] The symptoms use the exact wording from real tickets or logs
- [ ] Someone reproduced the failure and followed the fix on a clean environment
- [ ] Each cause has a way to confirm it and a way to check the fix
- [ ] The flowchart ends every branch at a fix or at support
- [ ] Logs and examples contain no secrets or customer data
- [ ] The source link and the versions in the table are current
- [ ] Owner, last reviewed and next review are filled in

## Revision history

| Date | Author | Change |
|---|---|---|
| {{YYYY-MM-DD}} | {{Name}} | First version |

Want to see it as a real wiki page? Open this template in the Folio demo, where it is a normal Markdown page.

How to use it

Step 1: Collect the symptoms from real reports. Take the exact error messages and wording from support tickets, logs and chat, not from the code alone. Paste them as written, because that is what readers will search for.
Step 2: Order the causes by how often they happen. Put the most common cause first, write the fix as steps, and add a check that the fix worked. Use the diagnosis flowchart when the reader must choose between several causes.
Step 3: Test it on a real failure, then tick the review checklist. Break the thing on purpose and follow the guide. Add what a support engineer needs to ask for if the guide does not help, and set the owner and the review date.

What makes a good troubleshooting guide

It starts from the symptom, not the cause. The reader does not know the cause yet. Title the guide with what they see ("Sync stays on pending"), and quote the error text exactly so a search for it finds the page.

It separates diagnosis from the fix. First a few quick checks that tell the causes apart, then one block per cause: how to confirm it, how to fix it, how to check that it is fixed. A reader who only wants the fix can skip the explanation.

It is honest about what it does not cover. A list of known issues and a clear last step ("send us these three things") keep readers from looping. The guide should say when to stop and ask for help, and what information makes that help fast.

It stays true. Record the versions it applies to, the owner and the date of the last review, and update it after every ticket it did not solve. A troubleshooting guide that nobody maintains misleads at the worst moment.

RunbookTrigger, triage flowchart, exact commands with expected output, rollback and escalation.How-to guideGoal in the title, prerequisites, one-action steps with expected results, a check and a review list.PostmortemBlameless incident review: impact, UTC timeline, causes, what went well, action items.

All templates

Questions

What is a troubleshooting guide?: A document that helps a reader find the cause of a problem and fix it, organised by the symptoms they see. It differs from a how-to guide, which describes a task that goes well, and from a runbook, which is a procedure for operators who respond to an alert.
How is a troubleshooting guide different from a runbook?: A troubleshooting guide is written for users, customers or colleagues who hit a problem, and starts from what they see. A runbook is written for on-call engineers who respond to an alert, and starts from the alert. The same incident can have both.
What should I put at the top of a troubleshooting article?: The exact error text or the symptom in the title, the versions or environments it applies to, and one line saying whether this is your problem. Readers decide in seconds whether to keep reading.
How do I write a diagnosis flowchart?: Use yes or no questions that the reader can answer by looking at one place, and end each branch at a fix or at "contact support". A Mermaid flowchart is plain text, so it can be reviewed and changed like the rest of the page. Keep it to about ten nodes; if it grows, split the guide.
How often should a troubleshooting guide be reviewed?: After every release that changes the feature, and at least every six months. Add any ticket that the guide did not resolve as a new cause or a new known issue.

Updated 13 October 2026.

Troubleshooting pages your team and the assistant can both find

In Folio a troubleshooting guide is a Markdown page in Git, next to the product documentation. The error text is in the page, so the built-in search finds it, and the built-in assistant can answer "why does sync stay on pending?" from the page; with a Sources: rule in its .agent folder it shows which page it used. Tables, code blocks and Mermaid flowcharts render in the editor, and the page history shows who changed a fix.

Open in Folio demo Install Folio Folio on GitHub