When an assistant misses an answer that “is definitely on the site”, teams reach for model settings. More often the page is written for a patient human who will scroll, not for a retrieval system that matches passages. The fix is editorial, and it is usually a few hours of work on the pages that already fail in your gap report.
This is the blog-length version of a practice we also document as a step-by-step in write docs your bot can answer from. Use the guide when you are mid-edit; use this post when you need the principles before you touch the CMS.
Answer in the first paragraph
State the fact, then explain. “You have 30 days to return unused items” belongs near the heading, not after a history of your packaging philosophy. Retrieval scores passages; a direct sentence next to a relevant heading is far more likely to surface than the same fact buried under four paragraphs of context.
Humans benefit from the same pattern. People scanning on a phone want the number first. The assistant is not asking you to write robotically — it is asking you to stop hiding the payload.
Name headings the way people ask
“Seat management” is your vocabulary. “How do I add another user?” is theirs. Headings that mirror questions retrieve better because the match is semantic and lexical at once. Your content gaps already quote visitor wording — steal those phrases as titles and H2s.
One topic per page
A mega-page covering billing, seats, permissions, and SSO will retrieve for all of them and answer none precisely. The matched chunk may be from the neighbouring section. Split by question until each URL has one job.
Keep the pages linked so a reader who follows a citation can continue. Splitting is not orphaning — it is making the citation honest.
Facts must exist as text
Pricing tables rendered only as images, fees that appear only in screenshots, and policies that live only in a PDF scan are invisible to retrieval. If a number must be answerable, it must appear as selectable text somewhere you index. Decorative visuals are fine; sole carriers of truth are not.
Keep contradictions out of the corpus
An old blog post that restates policy in friendlier language will sometimes win over the legal page. Either update the blog, add a clear “superseded” note and stop indexing it, or remove it from the knowledge sources. Retrieval cannot prefer the page you emotionally trust; it prefers the passage that matches.
Edit from refusals, not from pride
You do not need to rewrite the whole help centre. Rank refusals and near-misses for two weeks, then fix the pages those questions should have hit. After each rewrite, re-crawl or refresh that source and re-ask the failing questions in the playground with citation checks.
- Lead with the answer.
- Use question-shaped headings.
- One topic per URL.
- Put answerable facts in text.
- Retire competing outdated copies.
Good retrieval writing is mostly good support writing. The assistant just makes the structural weaknesses impossible to ignore.
