Writing help docs an AI can actually retrieve from
Retrieval doesn't read your documentation the way a person does — it fetches passages. A few small habits make the difference between an agent that answers and one that escalates everything.
If you point an AI agent at your documentation and the answers are vague, the model usually isn't the problem. Retrieval works on passages, not pages, and most documentation is written to be read top to bottom by someone who already has context. A handful of habits fix most of it.
Write so a passage can stand alone
A chunk pulled out of the middle of your article will be read without the four paragraphs above it. If a section says “click Save and you're done”, nothing in that passage says what was being saved. Repeat the subject in the sentence that carries the answer. It reads slightly redundantly to a human and it's the single biggest quality win for retrieval.
One question per section
Sections that answer three related questions retrieve badly for all three. Split them, and title each one with the question a customer would actually ask — “Can I export my data?” beats “Data management”. Headings are strong signal, and phrasing them as questions aligns them with the thing being matched against.
Use your customers' words, not your internal ones
Your team says “workspace member”. Customers say “seat”, “user”, “teammate”, “licence”. If none of those words appear anywhere in the article, keyword search can't find it and vector search is doing all the work alone. Mention the synonyms once, naturally — a line like “teammates (sometimes called seats)” is enough.
State the limits explicitly
Write down what the product doesn't do. “There's no Zapier integration yet; use webhooks” is retrievable. Silence isn't — and silence is exactly the gap where a model with no grounding starts improvising a plausible answer. The negative statements in your docs do more safety work than any prompt instruction.
Don't hide answers in screenshots and tables
A screenshot of a settings page is invisible to retrieval. So, mostly, is a dense pricing table. Put the answer in a sentence, then show the screenshot as confirmation. If a limit matters — file sizes, rate limits, retention windows — write it out in prose somewhere too.
Let real questions drive the edits
The best documentation backlog is your escalation list. Every conversation the agent handed to a human because it couldn't ground an answer is a gap someone can close in ten minutes. Do that weekly for a month and the shape of your queue changes.
Every question you answer twice is an article you haven't written yet.