How to write knowledge base articles, with examples

To write a knowledge base article, take one question customers really ask, put it in the title in their words and answer it in the first sentence. Then give the steps as a numbered list, with every button name and error message written out as text, and keep each fact next to the thing it’s about. Those habits help a customer who skims the page. They matter even more now that an AI agent reads your articles too, because the agent doesn’t read your articles top to bottom. It finds the few passages that match a customer’s words and answers from those alone.

Deacon is an AI customer support agent for founders who answer support themselves. It answers your customers in seconds from the articles you’ve written, says so when they don’t cover a question, and shows you what customers get stuck on, so you know which article to write next. There’s a free plan, and it needs no card.

Every article now has two readers

The first reader is a person in a hurry. When Jakob Nielsen tested how people read on the web, 79% of his test users scanned any new page and only 16% read it word by word. The study is old, but the habit is easy to recognise. A customer with a problem reads the title, glances at the first line and jumps to the step they need.

The second reader is an AI agent answering questions on your site. It doesn’t browse your help centre. It searches it, pulls out the few passages that best match the question and writes its reply from them. When the fact isn’t in those passages, a careful agent says it doesn’t know and a careless one guesses.

Both readers fail the same way, by not finding the article. In a Gartner survey of 5,728 customers in December 2023, the most common reason self-service failed, in 43% of cases, was that customers couldn’t find content relevant to their issue.

Start from the questions customers really send

Start from your inbox rather than your product’s menu. Four steps turn it into a list of articles.

1. Copy the last 50 or so questions from your email, chat and social replies into one list, in the customers’ own words.
2. Group the ones that want the same answer. “Can I get my money back?” and “refund??” belong together.
3. Sort the groups by how many people asked. The top ten are your first ten articles.
4. Title each article with the way most people asked it.

Give every question its own article. A person who lands on one from a search wants one answer, and an AI agent does better too, because a passage that holds one answer can’t be mixed up with the one beside it.

The shape of a good knowledge base article

Most good articles have the same five parts, whatever tool you publish them in.

1. A title that names the question or the task in the customer’s words, such as “How do I change the card I pay with?” rather than “Billing overview”.
2. A first sentence that answers it. For a yes-or-no question, start with yes or no.
3. The steps, as a numbered list, one action to a step, with the exact names of buttons and menus.
4. Anything that differs by plan, platform or version, each under its own heading.
5. What to do when it doesn’t work, quoting each error message word for word.

Leave out what doesn’t help someone halfway through a problem, such as the history of the feature, why you built it or a friendly sign-off.

How an AI agent reads your article

Most AI support agents work by a method called retrieval-augmented generation. Deacon, for one, drops your images, cuts each article into passages at your headings, searches them by meaning and by keyword, and hands only the best few to the model, which writes the answer from those alone. Grounding AI walks through each step as Deacon takes it, and other agents differ in the details rather than the idea.

Six writing habits follow from that.

• Put the customer’s words in your headings. A heading is part of every passage under it, so it’s the cheapest place to add the word people search for.
• Keep each fact next to what it’s about. “This costs extra” means nothing once it’s been cut away from the heading that says what “this” is.
• Write a procedure as a numbered list, so its steps travel together. Written as paragraphs, step four can land in a different passage from step one.
• Put every fact in words. A screenshot can sit beside the steps for people, but the steps themselves must be text.
• Quote error messages, setting names and plan names exactly. Keyword search can only match words it can see.
• Write down the no. If a plan leaves a feature out, or you don’t support a platform, say so in an article. An agent with nothing to go on can only decline, and a careless one fills the gap with what most products do.

Knowledge base article examples, before and after

Each of these six rewrites fixes a line that fails one reader or both.

Put together, a short article written this way looks like this.

How do I change the card I pay with?

You can change your card at any time in Settings. The new card is used from your next payment.

Change your card
1. Open Settings, then Billing.
2. Press Update card.
3. Enter the new card’s details and press Save.

If your card is declined
If you see “Your card was declined”, your bank refused the charge. Try another card, or ask your bank to allow it.

Paying by invoice instead
Invoices are available on yearly plans only. To switch, choose Pay by invoice in Settings, then Billing.

When there’s no article yet

The questions you haven’t written about are the hardest to find, because nobody tells you they went unanswered. An AI agent that declines instead of guessing turns each one into something you can see and fix.

In Deacon, every question your content didn’t cover waits in Conversations with an Answer this button. Write the answer, or jot down rough notes and press Tidy up with AI, which turns them into a clean question and answer and is told to use only the facts in your notes. Deacon also suggests a question that stands on its own, so a visitor’s “yes, that one” is filed under the thing they were actually asking about. If the question you save reads differently from what the visitor typed, Deacon keeps their wording with your answer, so the next person who asks it that way can find it by keyword too. Only a short one-word reply such as “yes” is left out.

Press Save & check, and Deacon asks itself the question again and shows you the reply it now gives. When it answers, it looks at similar open questions and tells you how many more your answer covers. On the Knowledge Sources page, Add Q&A takes up to ten ways of asking the same question, which is where your customers’ other phrasings go.

Every answer you write becomes part of what Deacon knows, so it needs you less over time. When a written answer and an older page both reach the model and disagree, Deacon is told to prefer yours.

Keep every article true

An out-of-date article is worse than none, because both readers trust it. A person hunts for a button that moved, and an agent repeats the old limit with total confidence.

• Give each article an owner and the date it was last checked.
• When you ship, list the articles the release touches and update them the same day.
• Merge articles that say the same thing in different words, because two versions drift apart.
• Refresh the agent’s copy too. In Deacon, fetch the changed page again and press Retrain agent. The old version keeps answering until you do, so customers don’t read an update you’re halfway through.

How Deacon answers from your knowledge base articles

Deacon turns the articles you’ve already written into answers, with no flows or decision trees to build. When you sign up, it learns by itself from your home page and main pages. Your help centre’s front page can be one of them. On a paid plan you can crawl the whole help centre, tick the articles you want and press Retrain agent. Despite the button’s name, no model is trained. Deacon cuts those articles into passages and indexes them, as above. A single article added by its address, a file or pasted text starts answering as soon as it’s been read.

From then on Deacon answers your customers in seconds, at any hour and in the language they write in, from the passages it finds for each question. An answer taken from one of your articles usually links to it, so a customer who wants every step can open the article. When your articles don’t cover the question, Deacon says it doesn’t know instead of guessing and asks for the visitor’s email. If they leave it or ask for a person, the owners on your team get an email, and your reply from the dashboard appears in their chat if it’s still open.

It also tells you which article to write next. Topics group what people ask, count the people behind each group and label most of them, as a how-to, a feature ask, a bug report and so on, so you write for the questions customers really have.

Knowledge is counted by the text Deacon takes from your pages, not by file size. A page of docs comes to about 15,000 bytes of text, so the free plan holds about 67 pages, Starter about 1,000 and Growth about 3,330. Every feature is on every plan, and the free plan has no end date. The pricing page has the rest.

Questions about writing knowledge base articles

What are the main types of knowledge base article?

Most help centres use five kinds. A how-to walks through one task. A troubleshooting article starts from a symptom or an error and fixes it. A reference article lists facts such as limits, plans or settings. A policy article states a rule, such as refunds or data deletion, exactly as you mean it. An FAQ page gathers short answers, each under its own question.

How long should a knowledge base article be?

As long as the answer needs. If an article needs several headings for different situations, check whether it’s really several articles. Length on its own doesn’t hurt an AI agent, because it reads passages rather than pages, but a person gives up on a page that makes them hunt.

Should I write for people or for the AI?

For people. One question per article, the answer first, steps in words and the customer’s words in headings help both readers. The one difference is screenshots. Keep them for people, but never let a screenshot carry a fact on its own.

Is one FAQ page better than separate articles?

For an AI agent, either works, as long as each question is its own heading, because every passage keeps the question it belongs to. For people, separate articles are easier to land on from a search, so give your most-asked questions their own.

Do I need a help centre before I add Deacon?

No. Deacon reads any public page on your website, uploaded files (PDF, Word, Markdown, text, CSV or HTML, up to 10 MB each) and text you paste in. Start with your pricing page and a few docs, and write answers as the questions come in. What an AI knowledge base is made of explains what to give it. If you want a help centre anyway, the best knowledge base software compares eight.

Can AI write my knowledge base articles for me?

It can draft them, but check every fact, because a model fills gaps with what’s typical rather than what’s true of your product. Deacon’s Tidy up with AI works the other way round. You supply the facts, and it’s told to build the answer from them and nothing else.