Template · Updated
Troubleshooting article template
Troubleshooting articles are where customers land when something is broken and they're already frustrated. A clear structure gets them to the fix fast, and when it doesn't, gets you a ticket with everything you need.
Short answer
A troubleshooting article starts from what the customer sees, not from how your system works. Name the symptom in their words, list the likely causes from most to least common, give a short fix for each, and end with exactly what to send support if none of them work. One symptom per article.
When to use this template
Use this template for problems customers hit repeatedly: something not arriving, not syncing, not showing up, or showing an error. Your inbox already tells you which ones: the tickets you answer with the same paragraph every week. Write one article per symptom, titled the way customers describe it. A good test: if your support team pastes the same explanation into tickets more than twice a month, it should be a troubleshooting article, and the pasted reply is its first draft.
What goes in it
A title that describes the symptom
Use the customer's words: “Client didn't receive the invoice email”, not “Email delivery issues”.
A one line summary of the usual fix
Many readers only need the most common cause. Put it right under the title.
Causes, most common first
Each cause gets a heading, a quick way to confirm it, and the fix. Order by how often it's the real reason.
What to send support
List the exact details that help you solve it: IDs, timestamps, screenshots, browser. The ticket arrives ready.
Related problems
Link symptoms that look similar but have different fixes.
The template
Copy it into your help center editor and replace the bracketed parts.
# [Symptom, as the customer says it]
[One line: the most common cause and fix.]
## 1. [Most common cause]
How to check: [quick test].
Fix: [steps].
## 2. [Second cause]
How to check: [quick test].
Fix: [steps].
## 3. [Less common cause]
How to check: [quick test].
Fix: [steps].
## Still not working?
[Contact support](link) with:
- [ID or reference]
- [When it happened]
- [Screenshot of the error, if any]Example: Ledgerloop's email delivery article
# Client didn't receive the invoice email
Usually the email went to spam or the address has a typo. Check both first.
## 1. It's in spam or promotions
How to check: ask your client to search for billing@example.com.
Fix: have them mark it as not spam, or resend from the invoice page.
## 2. The email address has a typo
How to check: open the client and look at the email field.
Fix: correct it and click Resend.
## 3. Their company blocks outside billing emails
How to check: the invoice shows “Bounced” in its activity.
Fix: send the invoice link directly, or ask them to allow billing@example.com.
## Still not working?
Email help@example.com with the invoice number and your client's email address.Mistakes to avoid
- Titling the article after your internal system (“SMTP delivery”) instead of the symptom customers see.
- Listing causes in a random order, so the most likely fix is buried.
- Fixes without a way to check whether that cause applies.
- Ending without telling the customer what to send support, so the ticket needs three follow ups.
- Covering five different symptoms in one long article.
How to keep this article current
Troubleshooting articles go wrong when error messages, statuses, or settings change. usedocs proposes an edit when a merged pull request changes an error message or status the article quotes, and the scheduled check flags fixes that reference settings that no longer exist. When customers ask the assistant about a symptom with no article, the question becomes a gap with a drafted troubleshooting article.
FAQ
How do I choose which troubleshooting articles to write?
Search your inbox for the problems you answer with the same reply every week; write those first.
Should each article cover one problem?
Yes, one symptom per article. Customers search for what they see, and focused articles are easier to find and cite.
How do I order the causes?
From most to least common, based on what actually fixed it in past tickets.
Should I include error codes?
Yes, quote the exact error text customers see, so searches and the assistant can match it.
What should the last section say?
Exactly what to send support, so the ticket arrives with everything you need.
What if the fix depends on the customer's setup?
Split the causes by setup, like browser, plan, or integration, and let readers jump to theirs. Say clearly which details support will need if none of them match.
Should troubleshooting articles link to the status page?
Yes, near the top. If the problem is an outage, the status page answers it faster than any list of causes.