How to write a knowledge base article

Every small support team already knows the questions it answers over and over. Turning one of those answers into a knowledge base article means you write it once and it keeps working while you sleep. Here's how to write a knowledge base article your customers can actually follow, in about twenty minutes.

What a knowledge base article is

A knowledge base article is a short help page that answers one question or walks through one task. "How to change your billing address" is an article. "Everything about your account" is not.

These pages live in your help center, where customers can find them any time without waiting for a reply. Knowledge base articles come in a few flavors:

• How-to steps. The most common kind. A task, in order, from start to finish.
• Fix-it guides. What to try when something breaks.
• Plain explainers. What a feature does and who it's for.
• Policy answers. Refunds, cancellations, shipping windows.

Most of what a small team needs falls into the first two. Start there.

Why knowledge base articles earn their keep

A support reply helps one person once. A knowledge base article helps everyone who asks that question from now on, including the ones who would never have written in and would have quietly given up instead.

For a small team the math is blunt. If twenty minutes of writing spares you five copy-and-paste replies a week, it paid for itself in the first month. The article also answers at 2am on a Sunday, which no small team can do.

There's a second payoff people miss. Writing the steps down forces you to notice how confusing the task is. Teams often find that a knowledge base article they meant to publish turns into a bug report, because the honest version of the steps runs nine items long.

Start with the questions you already answer

The hardest part of writing help content is usually picking the topic. Don't guess. Open your support inbox and look for the repeats.

A quick way to find them: skim the last hundred conversations and tally the ones that made you copy and paste an answer. If you tag your tickets, your tags do this work for you, which is one reason tracking a few support numbers pays off early.

Write down the top five. Those are your first five articles. Before you start, check that you haven't already written one. If you have, update it instead of adding a second page that says something slightly different.

How to write a knowledge base article, step by step

Once you have the topic, the writing itself is mostly a matter of getting out of the reader's way.

Title it the way a customer would say it

Use their words, not your internal ones. Your team might call it "payment method rotation." Your customer calls it "changing my credit card." Title the article "How to change your credit card" and it will get found by search and by your own help center's search box.

Put the main subject near the front, and add context only when it changes the steps. "Reset your password on iPhone" is worth splitting from the desktop version if the buttons differ. If they don't, one article is plenty.

Put the answer in the first two sentences

People don't read help pages, they hunt through them. In classic eye-tracking research, 79% of readers scanned any new page they landed on and only 16% read it word for word. Someone who is already annoyed enough to look up an answer is scanning even harder.

So lead with the answer. Say what the article does and what the reader needs before they start, like an account number or admin access. Then get to the steps. Save the background for the bottom, or cut it.

One step, one action

Number your steps and put exactly one action in each. "Click Settings, then choose Billing and hit Save" is three steps crammed into one line, and it's where people lose their place.

Name the button the way it appears on screen. If the screen says "Update payment," don't write "submit your new details." Write what they'll see.

Add a screenshot where people get stuck

You don't need a picture for every step. You need one at the spot where readers hesitate, usually a menu that's hard to spot. One good screenshot beats six decorative ones, and it keeps the page quick to load.

Say what "done" looks like

End with how the reader knows it worked, and what to do if it didn't. A confirmation email, a green badge, a changed date on the account page. Then link to the one or two articles they're most likely to need next.

A knowledge base article template you can copy

Here's the skeleton we use. Fill in the blanks and you have a working draft.

• Title: the task, in the customer's words.
• One-line summary: what this article helps you do.
• Before you start: anything the reader needs on hand.
• Steps: numbered, one action each, with the button names.
• How to check it worked: the thing they should see.
• If it didn't work: the two most common snags, and how to reach a human.
• Related: two links, no more.

That last line matters. A page that links to nine other pages sends people in circles.

What that looks like filled in

Say you run a small online shop and people keep asking how to change a delivery address after ordering. The finished knowledge base article reads something like this:

Change the delivery address on an order

You can change the address yourself until the order ships, usually within two hours of ordering. After that, contact us and we'll try to catch it.

Before you start: have your order number handy. It's in your confirmation email.

1. Log in and open My orders.
2. Find the order and select View details.
3. Select Edit next to the delivery address.
4. Type the new address.
5. Select Save address.

How to check it worked: the order page shows the new address, and you'll get a second confirmation email within a few minutes.

If there's no Edit button: the order has already shipped. Reply to your confirmation email and we'll contact the carrier.

Nothing clever about it. It names real buttons, it says how long the window is, and it tells you what to do when the happy path fails. That's the whole job.

Mistakes that make good articles useless

• Writing for your team. Jargon your customer has never heard means the article can't be found or followed.
• Answering three questions at once. Split it. Each knowledge base article should do one job.
• Burying the steps under a history lesson. Nobody needs two paragraphs of context to change a password.
• Letting it rot. An article describing a button that moved six months ago is worse than no article, because it costs trust.

Test a draft on someone who has never done the task. Every question they ask is a step you left out.

Keep articles alive after you publish

Publishing is the start. Put a recurring hour on the calendar once a month and check the pages people actually open. If a knowledge base article gets plenty of views and the same question keeps landing in your inbox anyway, the article isn't answering it. Rewrite the opening.

Update the article whenever you change the thing it describes. The teams who keep help content current are the ones who treat it as part of the release, not a chore for later. It's the cheapest way to reduce support tickets you'd rather not answer twice.

Let the support bot use what you wrote

Good help content does double duty. In SupportifyGPT, the knowledge base articles you publish feed the self-service knowledge base and the built-in support bot, which matches a customer's question against your articles by keyword and hands back the right one. It's rule-based automation, so it's only as good as what you wrote. Clear titles and plain steps are what make it land on the right page.

That's the real payoff of learning how to write a knowledge base article well. The same twenty minutes covers your help center, your support bot, and the reply your team would have typed by hand.

If you're still choosing where to put all this, our guide to knowledge base software covers what to look for. Or start a free trial and publish your first article today. Every plan includes the knowledge base, the help center, and the support bot, with no per-answer fee.