How to Write a Knowledge Base Article People Can Find and Use

A teammate asks the same question for the third time this week. You know the answer, and you're tired of typing it into chat. The fix is a knowledge base article: a short page that answers one question well enough that nobody has to ask again.

This guide covers how to write a knowledge base article that people can find, scan, and act on. It explains what to put in each part, how to word it, and how to keep it accurate after you publish. A copyable template is at the end.

What is a knowledge base article?

A knowledge base article is a short, self-contained page that answers one question or solves one problem for a specific audience. It describes the situation in the reader's words, gives the answer or steps, and notes when the answer applies. Customers read it in a help center; employees read it in an internal wiki.

The "self-contained" part is important. A knowledge article is not a chapter in a manual that only makes sense after reading the chapters before it. Someone should be able to land on it from search, read it, and leave with the problem solved.

Start with one question per article

The most common mistake is putting too much into one article. If a page covers "Billing" from top to bottom, it answers nothing quickly. A page called "How do I change the card on my account?" answers one thing completely.

Knowledge-Centered Service (KCS), a knowledge management methodology developed by the nonprofit Consortium for Service Innovation, says articles are typically a page or less. When a topic needs more than that, several short articles are linked together. That gives you three practical benefits:

• Easier to find. A focused title matches a focused search.
• Easier to keep current. When one step changes, you update one short page.
• Easier to reuse. A small article about resetting a password can be linked from ten other articles.

A quick test: if you can't write the title as a single question or task, split the article.

The four parts of a knowledge base article

You don't need to invent a structure. KCS uses a simple one that works in almost any knowledge base: issue, environment, resolution, and cause. When every article follows the same pattern, readers learn where to look, and writers spend less time deciding how to start.

Issue: describe the problem in the reader's words

Write the issue the way the person asking would describe it: what they're trying to do, what isn't working, or what they're looking for. KCS is specific on this point: the issue should be in the requestor's words and phrases, not internal terminology.

That matters for findability. A customer searches "can't log in after changing email," not "authentication identity mismatch." If your issue section uses their phrasing, search has a much better chance of matching it.

Environment: say when the answer applies

The environment lists the product, version, plan, device, or business process the answer applies to. For an internal article, it might be "Finance team, quarterly close, using the shared expense sheet."

This section stops a correct answer from being used in the wrong situation. It also tells you which articles to review when a product version or process changes.

Resolution: give the answer, then the steps

The resolution is the answer, workaround, or fix. If it takes several steps, number them. Put the outcome first and the explanation after. That pattern is known as the inverted pyramid, and Nielsen Norman Group recommends it for web writing because readers who stop after one sentence still get the main point.

Here's a resolution that leads with the answer:

You can change the card on your account from Settings → Billing. Changes apply to your next invoice.

1. Open Settings and select Billing.
2. Select Update payment method.
3. Enter the new card details and select Save.

Cause: explain why, when it helps

The cause is optional. Add it when two problems look the same but have different fixes, so readers can tell which article fits their case. Leave it out when it adds nothing, such as for a simple how-to.

Write for people who scan

Most people don't read help content line by line. In Nielsen Norman Group's well-known study of web reading, 79% of test users always scanned a new page and only 16% read word by word. In the same research, concise text improved measured usability by 58% and a scannable layout by 47%. The combined version, which was concise, scannable, and objective, scored 124% better than the control.

For a knowledge base article, that means:

• Use headings that answer questions. Plain-language guidance from Digital.gov recommends question headings when you know what your audience will ask, and specific statement headings as the next-best choice. "How do I export my data?" beats "Data export."
• Keep one idea per paragraph. If a paragraph covers two things, readers who skim will miss the second.
• Use numbered steps for procedures and bullet lists for options. Don't hide steps inside a paragraph.
• Bold the words a scanner needs: button names, menu paths, and the key fact.
• Keep nesting shallow. Digital.gov suggests no more than three levels of headings. Most articles need one or two.

Use plain language, not internal shorthand

Plain language isn't about simplifying the content. It means writing for the people who will actually read the article. Digital.gov's first rule is to write for your audience: use words they know, at the level of expertise they have.

A few habits help:

• Use active voice. "Select Save" is clearer than "The Save button should be selected."
• Replace jargon with everyday words, or define a term the first time you use it.
• Write instructions as commands. Start each step with a verb: open, select, enter, check.
• Keep it reusable. KCS advises leaving out details specific to one requestor, such as a customer's company name or contact information. Capture what you learned, not the story of a single ticket.

If your team has a shared documentation style guide, link to it from your article template so every writer follows the same rules.

Make the title do the searching

The title is the first thing a reader checks to decide whether an article is the right one. Good knowledge base titles tend to follow one of two patterns:

• A task: "Change the payment card on your account"
• A question or symptom: "Why can't I log in after changing my email?"

Avoid vague labels like "Account issues" or "FAQ #12." Put the most specific words first, and use the same terms your readers use in support tickets and chat messages.

Keep articles accurate after you publish

An article starts going out of date as soon as the product or process changes. KCS handles this with two ideas that work in any team:

• Reuse is review. Every time someone uses an article to answer a question, they're checking it. Articles that get used are the ones that stay accurate.
• Flag it or fix it. If a reader spots something wrong, they either fix it on the spot or flag it for the owner. Nobody should walk past a broken article.

To make that practical, give every article an owner, collect reader feedback on each page, and keep a version history so you can see what changed and roll back if needed. If you're starting from knowledge that lives only in people's heads, our guide to capturing tribal knowledge covers how to get it written down. Our post on improving documentation with user feedback explains how to turn reader comments into updates.

Knowledge base article template

Copy this structure into your editor or a Google Doc and fill it in:

Title: [Task or question, in the reader's words]

Issue: [What the reader is trying to do or what isn't working, in their words. One or two sentences.]

Applies to: [Product, version, plan, team, or process. List anything that changes the answer.]

Resolution: [The answer in one sentence.]

1. [First step, starting with a verb]
2. [Next step]
3. [Final step and the expected result]

Cause (optional): [Why this happens, if it helps readers tell similar issues apart.]

Related articles: [Two or three links to closely related articles]

Owner and last review: [Name or team] (internal only)

Before you publish, run a quick check:

• Does the title name a single task or question?
• Could someone who has never seen this product follow the steps?
• Is the answer in the first sentence of the resolution?
• Is anything specific to one customer or one ticket still in it?

Write one, then the next

A good knowledge base is built one clear article at a time, not from one large documentation project. Start with the questions your team answers most often, write each one with the same four-part structure, and let use and feedback show you what to improve.

If you want a place to write and publish these articles without technical setup, Sonat lets you draft in Google Docs or its built-in editor, keep version history and reader feedback on every topic, and publish a searchable knowledge base. For more on the bigger picture, see our knowledge management best practices.