How to Write a Knowledge Base Article (With a Template)
The anatomy of a help article that resolves the question instead of raising new ones: a task-based title, a one-line answer up front, numbered steps with a visual per non-obvious action, and the edge cases at the end. Includes a copyable template.
A knowledge base article resolves one question if it's built around the reader's task, leads with the answer, and shows every non-obvious step. Title it as the thing the reader is trying to do. Open with a single sentence that answers it for people who just need the gist. Give numbered steps, each starting with an action verb, with a screenshot or short walkthrough wherever the reader has to find something specific or the result isn't obvious. Close with the common problems and links to related articles. Keep it to one task per article — if it covers several, split it.
Title it as a task
The reader is searching for what they want to do, so the title should match that:
- Good: "How to change your billing email"
- Weak: "Billing settings overview"
Task-based titles also rank better, because they match how people phrase searches.
Lead with the answer
The first line is for the reader who just needs a pointer, not the full walkthrough:
To change your billing email, go to Settings → Billing and edit the Billing contact field. Changes take effect on the next invoice.
Someone who knows the product is now done. Everyone else keeps reading.
Numbered steps, one action each
- Start each step with a verb: "Click," "Open," "Enter," "Select."
- One action per step. "Open Settings and then click Billing and then find the email field" should be two or three steps.
- Name UI elements exactly as they appear, in bold.
- If a step has a condition, say so up front: "If you have multiple workspaces, switch to the one you want first."
A visual for anything non-obvious
Add a screenshot when the reader has to locate a specific control, or when the outcome of an action isn't visible. For a flow that moves through several screens, a series of screenshots gets confusing — the reader has to map each still onto their own screen. An embedded interactive walkthrough lets them follow the actual path instead:
For single steps, an annotated screenshot is enough — see how to annotate a screenshot.
End with edge cases and related articles
- "If this doesn't work…" — the two or three things that commonly go wrong, and what to do.
- Related articles — the next thing the reader is likely to need.
- A way to get help — a link to contact support if the article didn't resolve it.
Watch which articles get the most "was this helpful? no" votes and the most follow-up tickets. Those are the ones where a step is missing, wrong, or needs a visual. Help articles are living documents — the ones tied to changing UI need a review every few months.
Template
Title: How to [do the task]
[One-sentence answer with the path in bold.]
Steps
- [Verb] [exact UI element in bold].
- [Verb] …
- …
[Screenshot or embedded walkthrough for the non-obvious steps.]
If it doesn't work
- [Common problem] → [fix]
- [Common problem] → [fix]
Related
- [Link to the next likely task]
- [Link to a broader guide]
Still stuck? [Contact support.]
For building the whole help center rather than one article, see how to create a knowledge base. Related: how to create a step-by-step guide, how to document a process.
Frequently asked questions
How do you structure a knowledge base article?
Title it as the task the reader is trying to do ('How to change your billing email'). Open with a one-sentence answer for people who just need the gist. Then give numbered steps, each starting with an action verb, with a screenshot or short walkthrough for any step that is not obvious. End with common problems and related articles.
How long should a help article be?
As long as the task requires and no longer. A simple setting change might be three steps. A multi-part setup might be fifteen. What matters is that each step is a single action and nothing is padded. If an article covers several distinct tasks, split it.
Should knowledge base articles have screenshots?
For any step where the reader has to find a specific element or the outcome is not obvious, yes. Screenshots reduce the guesswork that causes support tickets. For a multi-step flow through a UI, an embedded interactive walkthrough often works better than a series of stills because the reader follows the real path.
What is the biggest mistake in writing help articles?
Writing from the product's structure instead of the user's task. An article called 'The Billing Settings Page' forces the reader to figure out which part solves their problem. An article called 'How to update your card' takes them straight to it. Organise by what people are trying to do.