One sentence is worth keeping in mind before building anything: an AI agent cannot answer better than what is written. If the answer does not exist in your documentation, it will not invent it well; and if it exists but is buried in the fourth paragraph of an article called "Advanced configuration", it is fairly likely never to be found.
That makes the knowledge base the ceiling of the system. And since most knowledge bases were written for a person browsing, there is work to do.
What an agent actually does with your documentation
It is worth understanding the mechanism, because it explains every recommendation that follows.
An agent is not "trained" on your documentation. What it does is retrieval: it splits articles into passages, converts them into vectors representing their meaning, and when a question arrives it finds the passages closest to that question and hands them to the model, which writes the answer with them in front of it.
Three practical consequences follow:
- The passage is the unit, not the article. What reaches the model is a few chunks, not the whole page. A chunk that does not stand on its own arrives without context.
- Search is by meaning, not by words. The customer using different words stops being a problem. The article not saying what it promises does not.
- It updates instantly. Fix an article today and the answer changes today. There is no retraining, which is why a stale article is a mistake that propagates immediately.
The seven changes that pay off most
1. One article, one question
The article covering "Billing" that explains inside it how to change plan, how to download invoices, what happens when a payment fails and how to request an invoice under a different tax ID is four articles written as one.
For a person browsing, it worked. For retrieval, it is a disaster: the passages from an article like that mix topics, and the one answering "my payment failed" arrives with two paragraphs about tax IDs attached for no reason.
Splitting it into four is the single best effort-to-result intervention available.
2. Title it with the customer's question
If you call it "Data retention policy" and the customer types "how long do you keep my information", the article has to be called the second thing.
This already mattered — it was the most expensive mistake in any help centre — and with semantic retrieval it matters more, because the title carries the most weight when a passage is compared with a question.
Practical rule: 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 introductory context, no "in this article we will look at". The answer first and the detail after.
The reason is twofold: the first passage is the one retrieved most, and if it contains the complete answer the model cites it well. And if the article is public, it is the same thing that gets a search engine to put it in a featured snippet.
4. Passages that stand on their own
Writing "as mentioned above", "this option" or "in the previous step" builds paragraphs that depend on what sits over them. When that paragraph travels alone, the pronoun loses its referent.
The test is simple: take any paragraph of your documentation, read it in isolation and see whether it makes sense. If not, rewrite it repeating the subject. It sounds redundant when reading the whole page and it is exactly what is needed.
5. Real tables
An HTML table gets retrieved well and cited well. A "table" made of dashes, tabs or a screenshot does not: at best it arrives as scrambled plain text, at worst it does not arrive.
This matters most in exactly what gets asked about: plan limits, prices, compatibilities, error codes.
6. Say what cannot be done
This is the part nobody documents and the one that prevents the most hallucinations. An agent asked about a feature that does not exist, with nothing written on the subject, tends to construct a plausible answer.
An article saying "data cannot be exported as XML; the available formats are CSV and JSON" closes that door. Known limits, integrations that do not exist and things still in development deserve their own article.
7. A visible date and a review tied to the product
A stale article is worse than none, because the customer acts on what it says and the agent cites it with exactly the same confidence as if it were true.
Calendar reminders do not work. What works is tying the review to the change: if the billing screen gets touched, the billing articles get reviewed before the deploy. It is one more box on the release checklist.
What no documentation will resolve
This is where most documentation projects disappoint, and it is not the documentation's fault.
There are two kinds of question and only one is answered by writing:
- "How do I change plan?" → has a writable answer. It is the same for everybody.
- "Why was I charged €340?" → does not. It depends on that account, that month and that plan.
At a SaaS, the second group is usually close to half the volume. No article, however well written, is going to reduce that half, because the article does not know who is asking.
Confusing the two groups is what leads to writing two hundred articles and watching volume drop 15%. The second group needs something else: a system that can check account state at the moment of answering.
It is worth doing the split before writing anything. A hundred real conversations, two piles. That percentage is the ceiling of what documentation can resolve, and knowing it prevents setting targets that will not be met.
Where to start if you already have documentation
Not by rewriting the whole catalogue. In this order:
First, the twenty most frequent questions. Take them from the conversation history, not from intuition. For each, check whether an article exists, whether the title matches how the customer phrases it, and whether the answer is in the first paragraph.
Second, the searches with no results in your help centre. It is the list of what is missing, written by your own customers and free. It is the most actionable report there is and the least looked at.
Third, whatever the agent answers badly. Once it is running, weak answers point at one specific article almost every time. Each one is a documentation task with the diagnosis already done.
Fourth, what cannot be done. One article per known limit.
How to tell it is working
Three signals, and none of them is the article count:
- Rephrasing rate falls. Fewer people write the same question again in different words.
- Searches with no results fall, and the remaining ones are about new things rather than the usual ones.
- [Coverage](/en/glossary/tasa-de-desvio) rises in the documentary group and stays flat in the group depending on the account. That last part is not a failure: it confirms the split was right.
A catalogue of two hundred articles nobody can find is worth less than twenty well titled. With an agent in front of it, that difference stops being an opinion and becomes measurable.
