How to Write Help Docs an AI Support Agent Can Actually Answer From
September 15, 2026 · 9 min read · by the hiy team
The short answer
An AI support agent does not read your help centre the way a person does. It retrieves a handful of passages per question and answers from those, so every passage has to stand on its own — answer first, one topic, exact numbers, the same name for the same thing everywhere. Nine edits do most of the work: one question per page or heading; the answer in the first two sentences; exact numbers instead of "generous"; one name per feature; no two pages that disagree; a date on anything that changes; a Known issues list kept by hand; a Common questions list for the things you answer weekly; and corrections for the statements you cannot rewrite yet. None of them require a new tool. All of them change what the agent says tomorrow.
The uncomfortable part: the agent will not fix bad docs. It will answer from them, faithfully, and cite them.
Why does documentation quality decide the agent's answers?
Because retrieval works in passages, not pages. When a customer asks "how many API keys can I have?", the agent does not open your Limits page and read down to the right row. It searches every passage you have given it, takes the few that score highest against the question, and answers from those. If the right sentence is buried in the middle of a page about authentication, under a heading that says "Other notes", it may not score at all — and a passage about rate limits that mentions keys may score higher.
So the question for every paragraph you write is not "is this true?" but "if this paragraph were the only thing the agent could see, would it answer the question correctly?" A good help page for people is a narrative. A good help page for an agent is a stack of paragraphs that each survive being read alone.
Each workspace can hold up to 10 API keys. Revoking a key frees its slot immediately.
Exports over 50,000 rows return 502. Workaround: filter to under 50,000 rows and export in parts. Added 12 Sep.
The nine edits
1. One question per page, or at least per heading
A page called "Managing your team" that covers inviting, roles, seat limits, billing per seat and removal is five answers in one retrieval unit. Each heading should be a question a customer would type, and the text under it should answer only that. "How many members can I add?" is a heading an agent can find. "Team management" is a filing label.
2. Put the answer in the first two sentences
Retrieval scores the passage; the model reads what was retrieved. A passage that opens with two sentences of context — "Teams are a great way to collaborate. Before adding members, you may want to think about roles" — spends its best real estate on nothing. Lead with the fact, then explain. "Growth includes up to 25 members. Additional members are billed per seat." Everything else can follow.
3. Exact numbers, never adjectives
"Generous limits", "plenty of storage", "fast support" are sentences an agent cannot quote and a model will happily fill in. Every limit is a number, every price is a figure with a currency, every window is a count of days. If the true answer is "it depends", write what it depends on, with the numbers for each case.
4. One name per thing
If the same feature is "Workspaces" on the pricing page, "Teams" in the app, and "Organisations" in the API reference, a customer asking about any one of them retrieves a third of your material. Pick one name. Where you cannot — the API really does say org — write the alias once, in the page that defines the thing: "A workspace (called an org in the API) …".
5. Kill the contradiction
Two pages that disagree are worse than one page that is wrong, because which one the agent cites depends on how the question was phrased. The classic pair is the old pricing page still indexed beside the new one. Search your own corpus for every number that has ever changed and make sure it appears once. If you cannot delete the old page yet — it is linked from a signed contract, say — use a correction (edit nine).
6. Date anything that changes
Limits, prices, supported versions, and anything with "currently" in it. "As of September 2026, exports are capped at 50,000 rows" gives the agent — and the customer reading the citation — the information they need to judge whether the answer is stale. It also gives you a search term when the number changes.
7. Keep a Known issues list, by hand
The question customers ask most when something is wrong is is it me, or is it you? No help page written before the bug existed can answer it. A list you keep by hand — what is broken, since when, the workaround, and when it was fixed — answers it from a row you wrote this morning. In hiy this is a list the agent looks up and quotes verbatim rather than paraphrasing, and the Support Agent's SaaS preset starts with one attached.
8. Keep a Common questions list too
Every support desk has twenty questions that make up most of its volume, and half of them are not "documentation" in any natural sense — "can I change my email?", "do you have a student discount?", "where is my invoice?". Give them a home as rows: a question, the answer in one or two sentences, a link. It is the fastest way to lift the share of questions the agent answers with a citation, and it keeps the answers exact, because the agent reads the row rather than reconstructing the reply.
9. Corrections, for what you cannot rewrite yet
Some things are wrong in the docs and you cannot fix the page today — the writer is away, the page is generated from a system you do not own, the old text is still the right citation for a different question. A correction is a statement that overrides the old passage on that question without deleting it. In hiy a correction wins whenever it and the corrected material would come up together, in its own wording, and the corrected passage stays searchable and citable for everything else. It is also how you close a gap the agent reported: answer the question once, in the words a customer would use to ask, and it is a source from then on.
What the agent does with each kind of material
| Material | How the agent uses it | How it fails when the material is bad |
|---|---|---|
| A prose help page | Split into passages; the best-scoring few are retrieved and paraphrased, with the passage cited | The right sentence is buried under an unrelated heading and a wrong passage outscores it; or two pages disagree and phrasing picks the winner |
| A list row (limits, prices, known issues, common questions) | Looked up and quoted exactly; never paraphrased, computed or converted | The row is missing, so the agent says so — or, in a weaker system, remembers a typical value instead |
| A correction | Overrides the corrected passage on that question, in its own words; the original stays for everything else | It is written as a note to yourself rather than in the words a customer would ask, so it is never retrieved |
What not to feed it
- The changelog as a source. Two hundred entries of "fixed a bug in exports" retrieve beautifully against any export question and answer none of them.
- Slack threads and internal wikis. They contain the truth, three earlier versions of the truth, and a joke. The agent cannot tell which is which and will cite the joke.
- Pages written for a crawler. Keyword-stuffed marketing copy scores well on retrieval and says nothing. The agent will retrieve it and produce a confident non-answer.
- Anything you would not want quoted back to a customer. The agent cites its sources. Internal margins, warehouse codes, and "we know this is broken but…" all count.
How to check the edits worked
Take ten real tickets from last month and ask the agent each one, in the customer's original words, in a sandbox where nothing counts. For every answer that is wrong or missing, find which of the nine edits would have fixed it — usually it is one, two or five — make the edit, and ask again. The 20-question test is the fuller version of this, with a grade for each outcome.
Then keep going after launch: the questions the agent could not answer wait in a queue, and each one is a passage you have not written yet.
The honest version
This is most of the work, and it is yours. A support agent is quick to install and slow to make good, and the slow part is documentation — not because the agent is limited but because it is faithful. It will answer from a bad page as readily as from a good one, cite it, and be exactly as wrong as the page.
Corrections are a patch, not a cure. They do not delete the old text, so a customer who reads the cited passage may still see it. Fix the page when you can.
Where to start
Do edits three and five first — exact numbers and no contradictions — because they close the most damaging failures, and they take an afternoon with a search box. Then start the two lists. If you are building on hiy, import your help site in one crawl, attach a Known issues list and a Common questions list from the Lists tab, and run your ten tickets in the Sandbox before anyone else sees it.
Questions people ask
How should help articles be structured for an AI chatbot to use them?
One question per page or heading, with the answer in the first two sentences, exact numbers instead of adjectives, and the same name for the same feature everywhere. The agent retrieves passages, not pages, so every paragraph has to answer its question when read alone.
Why does my AI support agent give different answers to the same question?
Usually because two passages disagree — an old page indexed beside the new one — and which is retrieved depends on how the question was phrased. Search your corpus for every number that has changed, make sure it appears once, and use a correction for anything you cannot delete yet.
What is a Known issues list and why does an AI support agent need one?
A list you keep by hand of what is broken right now, since when, and the workaround. It answers the most common question when something is wrong — is it me or is it you? — from a row written today rather than a help page written before the bug existed, and the agent quotes it verbatim instead of paraphrasing.