How to write help docs an AI agent can actually use

When an AI support agent gives a vague or wrong answer, the cause is usually not the AI. It's a help page that was vague or wrong to begin with, or two pages that disagree. The good news: the habits that make docs easy for an AI to use make them easier for humans too.

1. One topic per page

A single 'Shipping & returns & payments FAQ' page forces the agent to work out which paragraph applies. Separate pages with clear titles, such as 'Returning a sale item' or 'Cash on delivery: where it's available', give it exactly the right context.

2. Put the answer first

Start every page with the direct answer in one or two sentences, then the details and exceptions. 'You can return items within 15 days of delivery. Sale items can be exchanged but not refunded.' beats three paragraphs about your commitment to quality.

3. Write the exceptions down

Your team knows that COD isn't available on island pin codes, or that custom orders can't be returned. If it isn't written anywhere, the AI can't know it. Every 'except when…' your agents say out loud belongs on a page.

4. Use real numbers and names

• 'Within 15 days', not 'within a short period'.
• 'Orders over ₹1,499 ship free', not 'larger orders may qualify'.
• The actual plan, product and branch names customers use.

5. Remove the contradictions

Old pages linger. If last year's return policy is still published somewhere, the AI may find it. Onfre flags documents that contradict each other so you can archive the outdated one, but a quick audit before you start saves time.

6. Let the questions tell you what's missing

After launch, the best guide to what to write next is the list of questions the AI couldn't answer confidently. Onfre's weekly report shows exactly these gaps. Writing one ten-minute page often fixes dozens of future conversations.

Good docs are the cheapest support hire you'll ever make.