Knowledge-base article template
A fill-in skeleton for a single help-center article — title, prerequisites, numbered steps, a success check, and the failure cases most drafts leave out — so every answer has the same scannable shape a customer can act on; paste it into every new draft when your articles are inconsistent, wordy, or quietly failing to resolve anything.
This is the skeleton you paste into every new help-center article and fill in — one article, one task. It's the companion to a KB style guide: the style guide sets the house rules for voice and terminology; this gives you the shape to pour a single answer into so nothing load-bearing gets left out.
Design it for how people actually use a help center. They don't read — 79% of users scan any new page they land on and only 16% read word by word (Nielsen Norman Group). And the article has to actually finish the job: Gartner found only 14% of customer-service issues are fully resolved in self-service (Gartner, 2024). A visitor who can't scan to the answer, confirm it worked, and recover from the obvious failure just opens a ticket. Every field below exists to close that gap.
Fill in every [bracket]. Delete a section only if the article truly doesn't need it — but never reorder them. Customers learn your shape and rely on it.
Before you draft (30 seconds)
- Pick one type. How-to ("how do I…") or troubleshooting ("why is X broken"). One type per article — a concept explainer stuffed into a how-to is why articles get long and get abandoned.
- Pick the title. Write what the customer would type or say — a task or a symptom in their words, not a feature name.
The template
# [What the customer wants to do or fix — a task or symptom, in their words]
[One sentence: who this is for and what they'll have when they're done.]
**Before you start**
- [ ] [Prerequisite: permission, plan tier, or setting needed]
- [ ] [Anything they must have open or on hand]
## Steps
1. [Verb first. One action. Bold the on-screen label — e.g. Click **Settings**.]
2. [...]
3. [...]
**Check it worked**
[The one thing the customer sees or can do that confirms success.]
**If it didn't work**
- [Most common failure] -> [what to do]
- [Second failure, or: contact support and include [error code / screenshot]]
**Related**
- [The next thing they'll likely need — link]
Troubleshooting variant. For a "why is X broken" article, swap ## Steps for cause-and-fix pairs so a customer can jump straight to their symptom:
## Fixes
**If [symptom / cause A]:** [the fix]
**If [symptom / cause B]:** [the fix]
Still stuck? [Contact support and include [error code / screenshot].]
Fill each field like this
| Field | Fill it with | Common mistake |
|---|---|---|
| Title | The customer's task or symptom: "Fix a declined card" | The feature name: "Payment Gateway" |
| First line | Who it's for + the outcome, in one sentence | "In this article, we will explore…" |
| Before you start | Only true blockers — permission, plan, a setting | A wall of caveats no one reads |
| Steps | One verb-first action per numbered step | Two actions joined by "and" in one step |
| Check it worked | The exact signal of success (a green banner, a status) | Leaving the reader unsure it worked |
| If it didn't work | The top one or two failures + the recovery | Silence — so the failure becomes a ticket |
| Related | The next logical article | A dump of every vaguely-related link |
Worked example
# Fix a declined card
For account owners whose payment failed. This gets your subscription
active again in about two minutes.
**Before you start**
- [ ] You're the account owner (only owners can edit billing)
## Steps
1. Go to **Settings > Billing**.
2. Click **Update payment method**.
3. Enter a card that isn't expired and click **Save**.
4. Click **Retry payment**.
**Check it worked**
The banner turns green and the status reads **Active**.
**If it didn't work**
- Card declined again -> your bank blocked it; call the number on the card.
- "Not authorized" error -> you're not the owner; ask them to update it.
**Related**
- Change your billing email
Metadata (set before publish)
- Owner — a named person or team who can verify it's still correct
- Type — how-to or troubleshooting
- Last reviewed date, distinct from last edited
- Review cadence —
[6 months]for pricing/policy/security,[12 months]for stable how-tos - Audience — public or internal
- Contact driver it maps to, so you can measure whether it deflects tickets
Pre-publish gate
Nothing goes live until every box is ticked.
- Title is the customer's task or symptom, not a feature name
- First sentence answers the question — no throat-clearing
- Steps start with a verb, one action each, ending in a success check
- The top failure case is written down, not left to a ticket
- Skimming only the bold labels still lands someone on the answer
- No "simply", "just", "obviously", or "easy"
- Every link works and every image has meaningful alt text
- Owner and last-reviewed date are set
- Searched your top phrase for this topic — this article shows up in the first few results
The template isn't bureaucracy. It's the difference between an article that exists and an article that resolves. Same shape every time means the only thing a rushed customer has to figure out is their own problem — not how your help center works.
Continue exploring