How to write a knowledge base article that gets read

TL;DR. A knowledge base article does one job: answer one question for a reader who arrived from search, not from the sidebar. Write the answer in the first paragraph, then add the context underneath, then add the screenshots. The article that does this well is shorter than the article that tries to cover everything; the KB that ranks well is full of the short ones.

The single most repeated mistake in knowledge base writing is trying to make one article do the work of three. The reader hit the page from a search box, with a specific question and roughly thirty seconds of patience. They want the answer, then maybe the why, then maybe the screenshot. If your article opens with the history of the feature, they’re back on Google before paragraph two. This post is the practical guide to writing a knowledge base article that fits its job, plus the discipline that keeps your KB usable once you have fifty of them.

What a knowledge base article is, in one paragraph

A knowledge base article is a single page that answers one question (or covers one task) for one kind of reader. The reader almost always arrives via search — they typed a question into a search engine or your in-app search and clicked the result that looked closest. They aren’t here for the documentation tour; they’re here for the answer. A good article gives it to them in under a minute and lets them close the tab. A great article also tells them where to go next if the answer turns out to be the wrong one. Everything else is decoration.

How to write one: the seven-step recipe

A workflow that lands cleanly, in the order the article comes together.

Pick the one question. Write the question down before you write anything else. How do I reset my password? Not Password and account recovery. If the question is two questions, split the article in two.
Write the answer in one sentence. No setup, no throat-clearing. The answer becomes the first sentence of the body. Click your profile picture, then Account → Reset password. That’s it.
Add the context underneath. Why this works, when it doesn’t, what to do if the obvious-next-step fails. Keep it to three or four sentences. Most readers stop here.
Add the screenshot. One per non-obvious step. Annotate it so the reader doesn’t have to find the button in the screenshot — circle it, arrow it, label it. Captions beneath each one explain what to look for.
Add the edge cases as a separate section. Resetting your password if your email is out of date, in its own H2 below. The reader who needs it will scroll; the reader who doesn’t won’t be slowed down.
Add related-article links at the bottom. Two or three, no more. If this didn’t work, try: … The reader who bounced gets a soft landing.
Title the page for search. The title field is the bait. Use the words your readers use, not the words your product calls things internally. Reset password, not Credential management. See How to make them findable below for the depth.

That’s the recipe. Seven steps, in order. Most of the articles you’ve seen go wrong at step 1 or step 7.

The five types of knowledge base article

Most KB articles fall into one of five shapes. Knowing which shape an article is helps you write the right thing.

The FAQ-style answer. Short, direct, single-question. Can I export my data? Yes — go to Settings → Export. Two paragraphs at most. Most of your KB should be these.
The how-to. A short procedure, three to seven steps, with screenshots. How to invite a team member. The recipe in the previous H2 is the meta-shape for these.
The troubleshooting article. X isn’t working — try these things in this order. Lead with the most-common fix; end with if none of these work, here’s how to get help. Resist the urge to start with diagnostics; the reader wants the fix first.
The conceptual / explainer. How feature X works. Use sparingly — most readers don’t want concepts; they want outcomes. When you do write one, lead with why a reader would need to understand this, not here is what we built.
The reference page. Every available keyboard shortcut, listed. The reader is looking up a specific value; structure for find by Ctrl+F, not read top to bottom. Tables work well; long paragraphs don’t.

A KB whose articles all look the same is a KB nobody trusts to have the right shape. Mix the five types as the content demands.

Best practices most KB articles ignore

A short list of things the top-3 SERP results don’t make load-bearing. We do.

One article, one job. If you can’t write the article title as a single user question, the article is two articles. Password reset and account recovery is two. Split, link.
Front-load the answer. The first sentence is the answer. The first paragraph is the answer plus the most important context. The reader who reads only the first paragraph should leave with what they came for.
Write the way your readers search. Use the reader’s words in the title and the first paragraph. Your team’s internal name for a feature is almost never the reader’s search term.
Screenshots without arrows are decoration. A screenshot the reader has to find the button in doesn’t help; an annotated screenshot saves three lines of prose.
The article that hasn’t been edited in a year is the article that’s wrong now. Most KB articles drift faster than the product. Surface last updated on every page; re-read the top 20 articles every quarter.

The opinion this post stands behind: most knowledge base articles have too many headings. The reader didn’t ask for a tour of the topic; they asked one question. A page with seven H2s is usually three pages forced into one, and the reader can tell. If your articles all look like the complete guide to X, your KB is a collection of complete guides, which is what the reader already left Google to escape. Shorter, more, and linked.

How to make them findable

The strangest fact about a knowledge base is that nobody reads it top to bottom. Every article arrives a search box at a time. The article that ranks well in your KB’s search (and in Google) is the article that:

Has a title that is a question or a task. How do I reset my password? or Reset your password. Not Account management overview.
Mentions the reader’s exact phrasing in the first paragraph. If readers say forgotten password, your article should say forgotten password before it says credential recovery. The Nielsen Norman Group’s writing-for-the-web guide is the canonical source on this — readers scan, they don’t read, and the first few words of every paragraph carry the weight.
Has descriptive H2s. Reset your password is a good H2. Step 1 isn’t. Section headings should let a scanner jump to the right place.
Lives in a wiki whose search returns the right page on the first try. This last one isn’t a writing tip; it’s the load-bearing platform decision. A KB article in a wiki with bad search is half-invisible to its readers, however well-written. Sub-second loads + typo-tolerant search + spaces and labels that are real navigation — those are the features your KB platform either has or it doesn’t.

The wiki-platform side is its own decision; see our internal knowledge base and knowledge base software posts for what the platform decision actually looks like. Raccoon Page is not a help-center builder with branded themes and customer-portal logins; we’re the wiki the articles live in for teams whose KB is for the team itself, not for an external support audience. If the readers of your KB carry company badges, this is the shape we’re built for.

When a KB article isn’t the right shape

Sometimes the answer to the reader’s question isn’t a KB article at all. Three patterns where the article is the wrong tool:

The answer is a video. A 90-second screen-recording explains things some readers will never grasp from text. Don’t fight it. Embed the video; the article is the scaffolding around it.
The answer is a fix in the product. If the same how do I X question keeps getting asked, X is hard to find is the answer. Move the button, rename the menu, fix the empty state — and then write the article.
The answer is a conversation. Some questions are judgement calls, not procedures. A KB article that says it depends in six paragraphs is a KB article that should be a doc the team discusses in a meeting and refers to as the time we decided X. That’s a decision log, not a KB. The how to write a postmortem and how to write a PRD posts cover the shapes that aren’t KB articles.

The KB article is the short, single-answer shape. Stretch it and it stops being a KB article and starts being something else, often something worse.

Things people actually ask

What’s the difference between a knowledge base article and a help center article? Usually nothing. Help center article is the term customer-facing teams use; knowledge base article is the broader term that covers internal and external KBs. The what is a knowledge base explainer covers the category split in depth.

How long should a knowledge base article be? As short as the answer allows. A FAQ-shape can be 80 words; a how-to with seven screenshots can be 800. If an article keeps growing past 1,200 words, it’s probably two articles pretending to be one.

Should I include screenshots in every article? For procedures, yes — one annotated screenshot per non-obvious step. For FAQ-shape answers, no — screenshots slow down reading and the answer is the text. Match the visuals to the article type, not to a every article needs images rule.

How often should I update knowledge base articles? The top twenty by view count: every quarter. The rest: when something in the product changes that they describe. Surface a last updated date on every page; if an article hasn’t been touched in a year, assume it’s drifted.

Who should write the knowledge base articles? The people closest to the answer. Engineering should write the technical references; support should write the common-fix troubleshooting; the team that owns the feature should write the how it works. A KB written entirely by a docs team is a KB with a translation layer in the way.

How do I structure a knowledge base article? The recipe in the post above is the canonical seven steps: question → one-sentence answer → context → screenshot → edge cases → related links → searchable title. Most articles follow that shape with minor variations.

What’s a good knowledge base article example? The best examples on the public web are Stripe’s API docs, GitHub’s help center, and the Mozilla writing-for-knowledge-base guide itself. All three lead with the answer, link aggressively between articles, and avoid the complete guide shape that buries the question.

Should knowledge base articles live in HR / support software or in a wiki? Customer-facing help-center articles often live in help-center software (Zendesk Guide, Intercom Articles, Document360) because that software handles the customer- portal logins and branding. Internal-team KB articles belong in a wiki — same shape, different audience. The internal knowledge base post covers the split.

How do I get readers to actually use the knowledge base? Three things, in order: search that returns the right result on the first try; titles that match what readers search for; an article shape that delivers the answer in the first paragraph. Everything else is decoration.

If you have a wiki and a habit of writing articles in it, the next step is the platform under both. Our Free tier is three users, one space, a hundred pages, no card — enough to write the first ten articles and see if your team opens them on Tuesday. Keyboard-first search, sub-second loads, last updated badges that turn red when the article goes stale. The article is the scaffolding for the answer; we’re the platform the scaffolding doesn’t fall through.