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. Most of what follows is about being found.

Start from the questions customers really send

Your product’s menu is the wrong place to start. Your inbox is the right one, and 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, one way of grounding an AI’s answers in your content. Here’s what Deacon does with an article, step by step. Other agents differ in the details, but not in the idea.

• It reads the page’s main content and drops its images, alt text included. Menus, sidebars and footers are usually left out too, so a fact that lives only in a screenshot never reaches the agent, and one that lives only in a sidebar probably won’t.
• It cuts the article into passages at your headings. Every passage keeps the headings above it, so a heading like “Refunds on annual plans” labels every line beneath it, and one like “More details” labels nothing.
• Short sections are joined to the next one, each keeping its own heading, and a long section is split between paragraphs. A numbered list, a table or a block of code stays in one piece unless it’s very long.
• Each passage is searched along with the page’s title, the headings above it and a short line Deacon writes to place it within the article.
• Every question is searched two ways, by meaning and by keyword. Meaning is how “can I get my money back?” finds an article that only says “refund”. Keyword search looks first for passages holding all the key words of the question, and it matches plurals and other simple forms, so “refunds” finds “refund”. That’s how a pasted error message finds the one article that quotes it.
• Only the best few passages go to the model, up to five for a first question and up to eight for a follow-up, and it writes the answer from those alone.

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.

Every section answers one thing, every step is text, and the last section says plainly who can’t pay by invoice.

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. Crawl your help centre, tick the articles it should learn from and press Retrain agent. Despite the name, no model is trained. Deacon cuts the articles you chose 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. 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. The questions your articles didn’t cover wait in Conversations, each with Answer this. So you write for the questions customers really have, not the ones you guessed at.

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.

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.