Why Your Documentation Needs an AI Chat
Summary
- Over time, the rules written in documentation drift away from how things actually work. The root cause is that readers' questions never reach the people who maintain the documentation.
- As AI agents start to rely on documentation too, any gap between the documentation and reality will lead to mistakes by those agents.
- Adding an AI chat to your documentation turns readers' doubts into questions that reach the maintainers, so the documentation can keep being improved.
Introduction
This article is for people who write and maintain documentation, such as internal manuals and product manuals. It explains why you should add an "AI chat" that answers readers' questions to your documentation.
As a concrete example, we take an "expense reimbursement manual", which many companies have, and look at the problems of maintaining documentation and how an AI chat improves them.
Why do we write documentation in the first place?
As a company grows, the amount of communication needed to share information and rules increases rapidly, and it becomes difficult to tell each person directly. So the company starts to think about writing manuals for things like the rules for expense reimbursement. In short, the purposes of such a manual can be summarized as follows.
- Letting readers (employees) act on their own
- Employees can submit expense claims and the like by themselves, without asking the finance team.
- Making responsibilities clear
- It makes clear who approves what (for example, taxi fares require prior approval from your manager).
- Reducing mistakes
- It gives an objective way to check claims for errors, which reduces corrections and rejected claims.
A newly written manual serves these purposes well. About two years later, however, things start to change.
Over time, documentation drifts away from the real rules
As you keep maintaining a manual, problems like the following start to appear.
New rules stay unwritten
For example, suppose the rules change so that employees can claim internet costs for working from home. If the change is only announced in the company chat and never added to the manual, only the employees who know about it will claim the cost, and the others will not.
Information is hard to find
Each time a rule is added, a new page is added, and the information gets scattered across pages such as "Transportation Expenses", "Business Trips" and "General Expenses". As a result, employees no longer know which page to look at.
What people really need is not written
For example, once employees start traveling abroad, a question comes up: "For a receipt paid in a foreign currency, which day's exchange rate should I use?" In this way, the information people really need often becomes clear only after the manual is in use, not when it is written.
Pages contradict each other
Suppose the old "Transportation Expenses" page and the new "Travel Expense Policy" page give different amounts for the daily allowance. Each employee follows whichever page they found, so the amount claimed for the same kind of trip differs from person to person. Everyone is following the manual, yet the manual itself, which should be the source of truth, contradicts itself.
The root cause: readers' questions never reach the maintainers
What these problems have in common is that the questions of the readers, the employees, never reach the finance team that maintains the manual.
Employees' questions either reach the finance team one by one through chat or email, or are never asked and are handled however each employee sees fit. The finance team is busy answering individual questions and cannot find time to update the manual. Nor can they get an overall picture of which questions come up often or what the manual is missing.
In this way, traditional documentation tends to be a one-way street from maintainers to readers, and readers' questions disappear before they reach the maintainers. As a result, the manual is not updated, and the gap with the real rules keeps growing.
Without an AI chat. Documentation is a one-way street from maintainers to readers, and readers' questions do not reach the maintainers.
In the age of AI, the gap matters even more
Documentation is where an organization shares what is "correct" and what the "rules" are. From now on, not only people but also AI agents will likely do their work by referring to documentation.
For example, suppose you introduce an AI agent that checks expense claims. If the agent treats the daily allowance on the old "Transportation Expenses" page as correct, it will wrongly reject claims that are actually correct.
A person might notice that "this page may be out of date", but an AI agent acts exactly on what is written. So gaps and contradictions in documentation turn directly into mistakes by AI agents. Documentation from now on needs to be reviewed and updated frequently.
Version control of documentation also matters, but it is beyond the scope of this article.
An AI chat as a way to receive readers' questions and reflect them in the documentation
To keep documentation from drifting away from reality, you need both a way to receive readers' questions and a way to reflect those questions in the documentation.
- Receiving questions: Add an AI chat to the manual. Employees get answers based on the manual right away, and their questions are kept as a record.
- Reflecting them in the documentation: The finance team reviews the question record and adds to or fixes the pages. You can also have an AI such as Claude read the question record and suggest changes.
The AI chat's role ends at receiving readers' questions. It is the maintainers who fix the documentation. When these two are connected, documentation that used to be a one-way street becomes a cycle in which information flows between readers and maintainers.
With an AI chat. Readers' questions reach the maintainers as a record, and as the documentation improves, so do the AI chat's answers.
What changes with an AI chat
Adding an AI chat improves the four problems above as follows.
| Documentation problem | How the AI chat helps | Expense manual example |
|---|---|---|
| New rules stay unwritten | The questions that come in show where to add information | After repeated questions like "Can I claim internet costs for working from home?", add the rule for those costs |
| Information is hard to find | Readers get answers just by asking, without searching for pages. Even as the documentation grows, it does not get harder for readers | Employees only need to ask "Can I claim taxi fares?" |
| What people really need is not written | The AI chat answers "it is not documented" for anything that is not written. Those questions become candidates for what to add | To the exchange rate question, the AI chat answers "it is not stated in the manual" |
| Pages contradict each other | Comparing the questions, the AI chat's answers and the pages the answers were based on reveals inconsistencies between pages | From the answer to an employee who asked again after seeing an old page, you notice that two pages give different daily allowances |
Examples of AI chat answers
We added an AI chat to the expense manual of a fictional company and asked questions as an employee.
For anything written in the manual, the AI chat answers and shows the relevant page. Employees do not need to search for pages.
For anything not written, the AI chat does not guess, and answers that it is not documented. Such questions are clues to what should be added.
For the daily allowance question, the AI chat answered with the amount on the new "Travel Expense Policy" page. When the employee asked again after seeing the old "Transportation Expenses" page, the AI chat compared the update dates of the two pages in its answer, which revealed the inconsistency in the manual.
A question about the daily allowance and a follow-up. The AI chat shows both pages as references and points out that one of them is out of date.
Example: improving the manual based on a question
Let's use the exchange rate example to see how a question leads to an improvement in the manual.
- An employee asks the AI chat, "For a receipt paid in US dollars on a business trip abroad, which day's exchange rate should I use?"
- The AI chat does not fill in what the manual does not say with guesses, and answers, "It does not state which day's exchange rate to use."
A question about the exchange rate and the AI chat's answer. It says the information is not documented and shows the page it is based on.
- The finance team reviews the question record and notices that the same question keeps coming in. They decide on a conversion rule and add it to the manual.
The question record (Monjiro's "Q&A history"). Three questions about the exchange rate, worded differently, have come in.
Select a question to see how the AI chat answered it.
When you select a question, "Conversation" shows the question and the AI chat's answer.
- Once the added content is published, the AI chat answers the same question based on the new rule.
The answer to the same question after the rule was added and published. It explains that the rate on the payment date is used and how each payment method is handled, and shows the updated page.
The finance team benefits too. They spend less time answering the same questions one by one, and can use that time to improve the manual. Questions come in, the manual improves, and the answers get better. By keeping this cycle going, you can keep the manual in line with the real rules.
Conclusion
In this article, we showed that adding an AI chat to your documentation sets in motion a cycle that reflects readers' questions in the documentation, so the documentation can fulfill its original purpose: letting readers solve problems on their own.
Not just expense manuals, but many kinds of manuals and documentation, internal and external, probably face the same problems. You will feel the value of documentation with an AI chat most when you see the questions real readers ask about your own documentation.
Monjiro is a service that combines documentation writing and publishing with an AI chat. Just create and publish your pages, and the AI chat is set up for you. You can review readers' questions in "Q&A history". On the Free plan, you can publish one project with an AI chat for free.
You can try documentation with an AI chat right away by signing up.
