How to Write a Knowledge Base an AI Assistant Can Use

The first job is coverage. HelpDocs identifies three causes behind almost every poor AI answer, none of them model problems: the answer is not written down, the answer is written down several times in different ways, or the answer exists but cannot be reached (HelpDocs). The first is the most common.

Build the list from evidence, not from what you think customers ask:

• Searches on your help center that returned no results.
• The most common reasons for support tickets, emails and calls.
• Questions staff answer from memory because nothing is written down.
• Messages from the assistant's own logs where it said it did not know.

HelpDocs recommends matching each of your top ticket drivers and no-result searches to an article, and treating anything without a match as a gap the AI cannot fill (HelpDocs). It also makes a useful point about scale: a hundred articles that answer your top hundred questions will outperform four hundred that miss them.

Leave out what the assistant does not need. A guide on building knowledge bases for AI models in Towards Data Science notes that a support chatbot may only need factual and tutorial content about company policies and procedures, and that limiting scope helps keep the model from inventing out-of-scope answers (Towards Data Science). Internal debates, old drafts and marketing copy do not belong in the set the assistant reads.

Duplicates do more damage than gaps. HelpDocs explains why: a gap produces "I don't know," while a contradiction produces a confident answer that may be the outdated one, because retrieval has no way to tell which version you meant to keep (HelpDocs). Zendesk's guidance says the same thing in its list of best practices: remove duplicate articles and conflicting information (Zendesk help).

A quick test: search for your five most important topics, such as refunds, cancellations, pricing, delivery times and opening hours, and count how many articles could plausibly answer each one. More than one means retrieval is making an editorial decision you did not make. Merge the articles, or retire the older one.

Keep each article focused, too. Zendesk recommends covering one topic completely and avoiding articles that mix several unrelated topics (Zendesk help). The cleaning step in the Towards Data Science guide follows the same logic: remove duplicate and outdated content, standardize terminology, and split material so each chunk holds one clear idea (Towards Data Science).

Because the assistant reads passages, each section must carry its own context. Meilisearch's guide to chunking says chunks should be self-contained facts and should not be cut off in a way that changes the facts (Meilisearch). You get there through writing habits, not tooling.

Answer the title in the first paragraph. The opening passage is the one most likely to be retrieved. HelpDocs suggests reading only the first fifty words of ten articles and checking whether the title's question is answered (HelpDocs).

Repeat the noun instead of using a pronoun. Zendesk advises avoiding vague pronouns such as "it" or "they" and repeating the noun, because a chunk may lose the sentence that told the reader what "it" was (Zendesk help).

Repeat the topic in section text. Zendesk also recommends repeating the question or topic from the title so that context is not lost during chunking and questions are not separated from their answers.

Give complete answers. State the answer directly rather than implying it, include the conditions and exceptions, and avoid sending the reader elsewhere for the important part.

Here is the difference in practice:

Before:
  It can be changed in settings. They will need to confirm it first.

After:
  The delivery address on an order can be changed in Account settings
  until the order ships. The account owner must confirm the new
  delivery address from the link in the confirmation email.

The second version is longer and much more useful. Any passage cut from it still says what can be changed, where, until when, and by whom.

Structure helps the assistant find the right passage. Zendesk's formatting guidance for AI use is short and practical (Zendesk help):

• Use clear headings and subheadings to break content into logical sections.
• Use bullet points for facts and numbered lists for steps.
• Present alternative solutions as separate instructions, not nested sub-steps.
• Add written text for images, videos and diagrams, because the AI reads only text.
• Keep tables simple, since information in tables is harder for a language model to interpret than sentences.

Headings carry a lot of weight. HelpDocs warns that headings such as "Overview" or "More information" tell a retrieval system nothing; if you cannot tell what a section covers from its heading alone, neither can the assistant (HelpDocs). Write headings that name the task or question: "Reschedule an appointment by phone" rather than "Phone".

Use the customer's words. If your team says "deprovision a seat" and customers ask how to "remove someone", the article should contain both phrasings. HelpDocs suggests taking the top search queries and checking whether each exact phrase appears anywhere in your content (HelpDocs). Zendesk adds that terms should be defined in full and acronyms spelled out on first use (Zendesk help).

Nothing important should live only in a picture. A price in a screenshot, a step shown only in a video, or a policy inside an attached file may be invisible to the assistant. HelpDocs suggests a direct test: ask the assistant about three facts that appear only in visuals, and add text for any it cannot answer (HelpDocs).

A simple article template that follows these rules:

# How do I reschedule an appointment?

You can reschedule an appointment online or by phone. [State the
rule, the deadline and any fee in this first paragraph.]

## Reschedule an appointment online
1. Open the booking confirmation email and select "Manage booking".
2. Choose a new date and time.
3. Select "Confirm". A confirmation email for the new time follows.

## Reschedule an appointment by phone
Call the front desk during opening hours and give the name on the booking.

## Rescheduling an appointment at short notice
[State the short-notice rule and who can make exceptions.]

Some assistants do more than answer questions. They take actions: look up an order, book a slot, start a return. For those, the knowledge base doubles as the assistant's instructions. OpenAI's guide to building agents recommends turning existing operating procedures, support scripts and policy documents into routines for the agent, and notes that in customer service these routines can roughly map to individual articles in a knowledge base (OpenAI).

The same guide gives three rules that apply to any procedure article:

1. Break tasks into small, clear steps. Dense paragraphs leave room for misreading.
2. Make every step a specific action or output. "Ask for the order number" or "check the delivery date" is better than "verify the details".
3. Capture the edge cases. Say what to do when information is missing, when the customer asks something unexpected, or when the normal path does not apply.

Policies deserve the same treatment. A refund policy written as a paragraph of legal prose is hard for an assistant to apply correctly. Rewrite it as the conditions that decide the outcome: who qualifies, within what period, for which products, with what proof, and what happens in each case. Keep the original legal wording in a separate article if you need it, and make sure the two never disagree.

Write the escalation rule into the procedure itself. If refunds above a certain value need a manager, the refund article should say so in plain words, so the assistant hands the case to a person instead of approving it.

A knowledge base that an AI reads is a production system. HelpDocs recommends treating it like one, with known owners, review cycles, access rules and a way to tell when it is wrong (HelpDocs). Stale content is the most common cause of an answer that is wrong on today's facts, because nothing announces that an article has aged.

Three habits keep it healthy:

• Owner and review date on every article. Tie reviews to changes in the business: a price change, new hours or a revised policy should trigger an update the same day.
• A gap review every week or two. Read the questions the assistant could not answer and the conversations staff had to correct. Zendesk notes that AI tools can help here by analyzing solved tickets to surface gaps and outdated articles (Zendesk).
• Access rules where the content lives. An assistant will surface anything it can read. HelpDocs advises testing by asking a customer-facing assistant something only staff should know, and fixing any leak with permissions rather than by asking the AI to keep a secret (HelpDocs).

Finally, check the citations, not just the answers. Connect the assistant, ask five real questions, and look at which article each answer came from. A right answer drawn from the wrong source is a problem you want to find before your customers do.