Knowledge base article template
Five skeletons you fill in, not five articles about writing articles.
Five outlines to paste into an editor and fill in: a how-to article, a troubleshooting article, an FAQ entry, a policy or terms explainer, and a release note. Each one is the skeleton of an article your customers actually search for, not an essay about how to write documentation.
Every blank is in [square brackets]; there are no automatically-resolving tokens here, because these are article outlines, not replies sent to one customer. Fill in the title, the steps, and the specifics, then delete the brackets and publish.
Core article types
How-to article
[Title: the task, phrased the way a customer would search for it. Example: Change the email address on your account] Who this is for [One line. Who needs this, and any plan or permission it requires.] Before you start - [Anything they need open, installed, or allowed] - [How long it takes, if it is more than a minute] Steps 1. [Action. Start with the verb. Name the exact button or menu label they will see.] 2. [Action. One action per step, never two.] 3. [The step that confirms it worked.] How to tell it worked [What appears on screen: a confirmation, a changed value, an email.] If it did not work - [The most common failure and the one line that fixes it] - [Link to the troubleshooting article] Related - [Link] - [Link]
What to change: Title it with the task, not the feature name. Hold it to five to seven steps; if you need more, it is two articles that link to each other.
Troubleshooting article
[Title: the symptom in the customer's words. Example: My emails are landing in spam] What you are seeing [One or two lines describing the symptom, so the reader knows they are in the right place.] Most likely cause [The one cause that explains most of these reports. Only one goes here.] Fix 1. [Step] 2. [Step] 3. [How to confirm it is fixed] Other things it could be [Cause 2] - [How to check] - [How to fix] [Cause 3] - [How to check] - [How to fix] Still stuck [Exactly what to send us so we can help on the first reply: screenshot, account email, the time it happened.]
What to change: Lead with the single most likely cause and its fix, not a list of everything it could be. Title it with the symptom a customer would type, never the internal name of the bug.
FAQ entry
[The question, written exactly as a customer would ask it, ending in a question mark] [The direct answer in one or two sentences. If it is a yes or no question, the first word is yes or no.] [One paragraph of the detail that actually matters: numbers, limits, timing.] [If there is something to do, one short list of steps or a single link. Nothing else.] Still need help? [Link to your contact page or the fuller article]
What to change: Answer in the first sentence, then explain. One question per entry so it can be linked and sent on its own. If the answer needs more than about 150 words, it is a how-to article, not an FAQ entry.
Policy and change articles
Policy or terms explainer
[Title: name the policy plainly. Example: Refund policy] The short version [Two lines maximum. The answer most readers came for.] What is covered - [A case that qualifies] - [A case that qualifies] What is not covered - [A case that does not qualify, said kindly and without hedging] - [A case that does not qualify] Time limits [The window in days, and when the clock starts.] How to request it 1. [Step] 2. [What to include] 3. [How long a decision takes] Exceptions [When you make one and who decides. If you never do, say that here.] Last updated [Date]
What to change: Say the exclusions in the same plain voice as the inclusions. A policy page that buries the no creates more tickets than it prevents. Keep the date honest, it is the first thing an annoyed customer checks.
Release note or what changed
[Title: date or version, plus a plain headline. Example: March 4: faster search and two fixes] What changed [One or two lines a non-technical customer understands. Lead with the benefit, not the mechanism.] New - [The feature, then why it matters in half a sentence] Improved - [The change, and what it feels like now] Fixed - [The bug as the customer experienced it] Anything you need to do [Usually nothing. If so, write "Nothing" and move on. Otherwise: the one action and the deadline.] Questions [Link to your contact page]
What to change: Write fixes as the customer experienced them, not as the ticket was titled. "Fixed a bug where the export button did nothing in Safari" is useful; the internal summary is not. Drop any of the three lists that is empty rather than writing "none".
Frequently asked questions
Do I need all five article types to have a useful knowledge base?
No. A small team usually gets the most value from how-to articles and FAQ entries first, since those answer the questions customers ask most often. Troubleshooting articles matter once you have a product complex enough to fail in more than one way, and policy explainers and release notes are worth adding once you have a policy worth writing down or changes worth announcing.
What's the difference between a how-to article and an FAQ entry?
Length and shape. A how-to article walks through numbered steps to accomplish a task and can run to a screen or more; an FAQ entry answers one question in a sentence or two, then stops. If an FAQ answer needs more than about 150 words or a list of steps, it has grown into a how-to article and should be split out and linked to instead.
How often should a knowledge base article be updated?
Whenever the thing it describes changes, and reviewed on a schedule beyond that, because a support article with a wrong price or an old screenshot causes more tickets than not having the article at all. The policy or terms explainer skeleton has a "Last updated" line for this reason; keep that date honest rather than stamping it on every deploy.
How long should a knowledge base article be?
Short enough that a customer skimming it on their phone finds the answer without scrolling past it. A how-to article that runs past one screen is usually two tasks pretending to be one; split it and link the two articles to each other rather than lengthening a single page.