Troubleshooting guide template

Copy the template

---
owner: "[accountable person]"
reviewer: "[subject-matter expert]"
status: draft
last_verified: "[YYYY-MM-DD]"
next_review: "[YYYY-MM-DD]"
locale: en
source_article_id: "[stable identifier]"
---

# [Something] is not working

> **Short answer:** [Name the most likely cause and first safe check. State what not to retry if it could cause duplicate charges, emails, or data.]

## What you are seeing
[Quote the exact error or describe the symptom. Include the affected version or environment.]

## Check these first
1. [Fast, reversible check.]
2. [Permission or account check.]
3. [Service-status or integration check.]

## Fix the problem
[Group fixes by cause. Explain what each action changes. Avoid destructive resets as a first step.]

## Verify the fix
[An observable test, plus the expected result.]

## If it still fails
Contact [support channel] with:
- The time and time zone.
- The affected page or item identifier.
- The steps you tried.
- A redacted screenshot or exact error message.

Never send passwords, access tokens, or payment card details.

## Author's preflight (remove before publishing)
- [ ] I tested the steps with the intended role.
- [ ] All UI labels match the product.
- [ ] The short answer includes important limits.
- [ ] No placeholder, secret, or real customer data remains.
- [ ] Related links and screenshots are current.
- [ ] An owner and review date are assigned.
- [ ] Any translations or embedded copies are queued for review.

This is the troubleshooting guide blueprint from the free Compass kit, unchanged. View the Markdown file on GitHub ↗

How to fill in each section

• Title. Use the symptom or the exact error text the customer can see, such as “Invitation emails are not arriving”. People search for what is on their screen, not the internal feature name.
• Short answer. Name the most likely cause and the first safe check. If retrying could create a duplicate charge, email, or record, say so here.
• What you are seeing. Quote the error and name the version or environment, so readers can tell quickly whether the article is about their problem.
• Check these first. Order checks from fastest and most reversible to slowest: a quick check, then permissions, then service status or integrations.
• Fix the problem. Group fixes by cause and explain what each action changes. Keep destructive resets out of the first steps.
• Verify the fix. Describe a test the reader can run and the result they should see.
• If it still fails. List the details support needs, and remind readers never to send passwords, tokens, or card numbers.

The front matter at the top (owner, reviewer, last verified, next review) keeps someone accountable for the answer after launch. The author’s preflight checklist is for you; remove it before publishing.

A filled-in example

Here is the template completed for Acme, the fictional product used across Compass. Replace every detail with behavior you have verified in your own product.

Every product detail above is invented for the example.

When a troubleshooting article is the right format

Use it when a customer sees something going wrong and wants it fixed: an error message, a failed sync, a missing email. If the reader wants to complete a task that works as designed, write a how-to article instead. If the answer is a rule, such as a refund window, use a policy article that the owner of that rule reviews.

Write one article per symptom. When two problems share a first check but need different fixes, give each its own article and link them, so search results land on the right one.

Common questions