An AI agent cannot answer better than what is written. If the answer is not in your documentation, it will not make up a good one. And if it sits in the fourth paragraph of an article called "Advanced configuration", the agent will probably never find it.
That makes the knowledge base the limit of what the agent can do. Most knowledge bases were written for a person browsing, so there is work to do.
How do you prepare documentation for an AI agent?
An agent does not learn your documentation. It splits it into passages and retrieves the ones closest to the question. So write one article per question, title it the way the customer asks it and put the answer in the first paragraph. Make every paragraph understandable on its own, use proper tables instead of screenshots, document what cannot be done and review articles whenever the screen changes. Start with the twenty most frequent questions and the searches with no results. And expect that about half your conversations, the ones that depend on the customer's account, will not be answered by any article.
What an agent does with your documentation
Knowing how it works explains every recommendation that follows.
An agent is not "trained" on your documentation. It does retrieval: it splits articles into passages and turns them into vectors that represent their meaning. When a question comes in, it finds the closest passages and hands them to the model, which writes the answer with them in front of it.
Three consequences follow:
- The model gets a few passages, not the whole page. A passage that does not make sense on its own arrives without context.
- Search is by meaning. A customer using different words is no longer a problem. An article that does not say what its title promises still is.
- Changes apply immediately. Fix an article today and the answer changes today. There is no retraining, which is also why a stale article shows up in the answers right away.
The seven changes that help most
1. One article per question
An article called "Billing" that explains how to change plans, how to download invoices, what happens when a payment fails and how to request an invoice under a different tax ID is four articles in one.
For a person browsing, it worked. For retrieval, it is a problem: the passages mix topics, and the one that answers "my payment failed" comes with two paragraphs about tax IDs that have nothing to do with it.
Splitting it into four is one of the cheapest changes you can make, and one of the ones that improves answers most.
2. Title it with the customer's words
If you call it "Data retention policy" and the customer types "how long do you keep my information", the article needs the customer's title.
This already mattered in any help center. With search by meaning it matters more, because the title carries the most weight when a passage is compared with a question.
If the title is not a question, make it the answer. "Data is kept for 90 days after cancellation" works better than "Data retention".
3. The answer in the first paragraph
No introduction, no "in this article we will look at". The answer first, the detail after.
The first passage is the one retrieved most often, and if it holds the complete answer, the model cites it well. If the article is public, that is also what a search engine needs to feature it in the results.
4. Paragraphs that stand on their own
"As mentioned above", "this option" or "in the previous step" make a paragraph depend on what sits above it. When that paragraph reaches the model alone, nobody knows what it refers to.
To check, take any paragraph, read it in isolation and see whether it makes sense. If it does not, rewrite it and name what you are talking about. It reads as repetitive on the full page, but it is what the agent needs.
5. Tables that are tables
An HTML table is retrieved and cited well. A "table" made of dashes, tabs or a screenshot is not: at best it arrives as scrambled text, and as an image it does not arrive at all.
This matters most for what people ask about most: plan limits, prices, compatibility and error codes.
6. Say what cannot be done
Almost nobody documents it, and it prevents more hallucinations than anything else. An agent asked about a feature that does not exist, with nothing written about it, tends to put together an answer that sounds right.
An article saying "data cannot be exported as XML; the available formats are CSV and JSON" prevents that. Known limits, integrations that do not exist and features still in development deserve their own article.
7. A visible date and reviews tied to the product
A stale article is worse than no article. The customer does what it says, and the agent cites it with the same confidence as if it were true.
Calendar reminders do not work. What works is tying the review to the change: if someone touches the billing screen, the billing articles get reviewed before the deploy. It is one more box on the release checklist.
What no documentation will answer
This is where most documentation projects disappoint, and it is not the documentation's fault.
There are two kinds of question, and only one can be answered by writing:
- "How do I change plans?" can be answered in writing. The answer is the same for everybody.
- "Why was I charged €340?" cannot. It depends on that account, that month and that plan.
At a SaaS company, the second kind is usually close to half the volume. No article will reduce that half, however well written, because it does not know who is asking.
Mixing up the two is how teams end up writing two hundred articles and seeing volume drop by 15%. The second kind needs a system that can check the customer's account while it answers.
Do the split before you write anything. Take a hundred conversations and sort them into two piles. The share in the first pile is the most documentation can resolve. Knowing it keeps you from setting targets you will not hit.
Where to start if you already have documentation
Do not rewrite every article. Go in this order:
- The twenty most frequent questions. Take them from your conversation history, not from intuition. For each one, check whether an article exists, whether its title matches how customers phrase it and whether the answer is in the first paragraph.
- Searches with no results in your help center. It is the list of what is missing, written by your own customers, for free. Few reports are this useful, and hardly anyone looks at it.
- Whatever the agent answers badly. Once it is running, a weak answer almost always points to one specific article, so you already know what to fix.
- What cannot be done: one article per known limit.
How to tell it is working
Three signals. The article count is not one of them:
- The rephrasing rate falls: fewer customers ask the same question again in different words.
- Searches with no results fall, and the remaining ones are about new things.
- Coverage rises for the questions documentation can answer and stays flat for the ones that depend on the account. That confirms the split was right.
Twenty well-titled articles do more than two hundred that nobody can find. With an agent answering, you can also measure it.
Frequently asked questions
Do I have to rewrite all my documentation before connecting an agent?
No. Connect what you have, see what it answers badly and fix those articles. The agent is the fastest way to find out what is missing. Before you start, it is worth splitting the articles that mix topics and retitling the twenty most read.
Does the agent read screenshots and videos?
No. Anything that only exists in an image does not exist for the agent. Put in text what the screenshot shows: the button name, the path, the limit.
Can I give it internal documentation without publishing it?
Yes. An agent can read internal notes and use them to answer without the customer seeing the document. It is how you get out of one person's head what only that person knows. More in do I need a help center to use a knowledge base?
Which language do I write in if I have customers in several?
One, and write it well. The agent answers in the customer's language even if the article is in another. More in which languages does an AI agent answer in?
How long until it shows?
Changes to the documentation apply immediately. What takes time is measuring: one or two weeks watching the rephrasing rate to know whether the new articles work.
