How to Format Your Docs So an AI Chatbot Answers Correctly

When an AI support agent gives half an answer, quotes last year's price or cannot find something your help center plainly covers, the cause is usually the documents, not the model. Retrieval-based chatbots answer from short passages found by meaning, and ordinary web writing falls apart when it is cut into passages: headings drift away from their answers, tables lose their headers, and "see above" points at text the model never receives.

Read on if you maintain the content an AI agent answers from, as a support lead, a founder or a technical writer. The sections below cover how a chatbot reads documents, twelve rules with before-and-after examples, a file format comparison, one rewritten policy page and a routine for keeping docs and agent in sync.

The worked example is PepoChat, our own AI support agent. Every PepoChat detail was read from its ingestion and search code on 19 October 2026, and we ran sample pages through that code to show what the agent receives; vendor guidance from OpenAI, Microsoft and Anthropic was read the same day. The rules are retrieval mechanics, not PepoChat features, so they apply to any tool built the same way.

How does an AI chatbot read your documents?

A retrieval-based AI chatbot reads your documents in pieces. It converts each document to plain text, splits the text into chunks, and when a visitor asks something, it fetches the chunks closest in meaning to the question and writes the answer from those alone. Whatever those chunks do not say, the model does not know.

A chunk is a passage, usually a few paragraphs or less, that is stored, searched and handed to the model as one unit. An embedding is a list of numbers that represents a chunk's meaning, so a chunk about refunds sits close to a question about getting money back even when the words differ. The RAG explainer covers the theory; the steps below show what one real pipeline does, because every rule in this guide follows from them.

What PepoChat does with a document

PepoChat's pipeline, as read in its code on 19 October 2026, runs in five steps:

1. Extract. A web page is fetched as the server sends it, without running scripts. PepoChat keeps the main content (a single <article>, else <main>) and drops menus, the site header and footer, sidebars, forms, dialogs, buttons and containers marked aria-hidden="true". The rest becomes Markdown in code, with headings, lists, links and tables kept and each image replaced by its alt text; the website import docs summarise this clean-up.
2. Split. The text is cut into chunks of up to about 1,000 characters, roughly 150 to 180 words, at line breaks. Chunks do not overlap, and the cut falls wherever the next line would pass the limit, not at a heading.
3. Embed. Each chunk is embedded from its own words with OpenAI's text-embedding-3-small model. The source's title is shown to the model beside the chunk, but the title is not part of the chunk's embedding.
4. Retrieve. The agent searches with the visitor's question written as a full sentence. The 30 nearest chunks are fetched and the best 8 kept, up to 12,000 characters in all, each without the chunks around it.
5. Answer. OpenAI's gpt-4o-mini reads those chunks with instructions to use only what they say, and the agent offers a person when nothing fits.

The consequence fits in one sentence: every chunk has to make sense alone, because it is found alone and read alone.

Other tools chunk differently, and none of the differences rescue a vague paragraph. OpenAI's file search documentation splits files into chunks of up to 800 tokens that overlap their neighbours by 400 tokens by default. Microsoft's Azure chunking guide, updated in May 2026, lists fixed-size, sentence-based, layout-based and semantic chunking among other approaches, and warns that chunks without enough context to answer a query can produce poor results. Anthropic's contextual retrieval research adds a short machine-written context to every chunk before embedding, which in its September 2024 tests cut failed retrievals by 35%, or 49% with keyword search added. Writing that context into the text yourself works in every tool.

How do you write documentation an AI chatbot can answer from?

Write chunking-friendly documentation: every section answers one question, opens with the answer and carries its own context, so any 1,000-character slice of it still makes sense alone. Each rule below fixes one way a passage loses its meaning when read by itself.

The same rules serve human readers. In Jakob Nielsen's 1997 study How Users Read on the Web, 79% of test users scanned any new page and only 16% read word by word, and the remedies were meaningful subheadings, one idea per paragraph and the conclusion first. Nielsen Norman Group's 2020 update, How People Read Online, found people still mostly scan. A section a skimming customer can use is usually a chunk a chatbot can use.

1. Give every heading one question, in the customer's words

PepoChat's agent searches with the visitor's question as a full sentence, so a heading phrased the way customers ask shares both their words and their meaning. One heading should cover one question: a section called "Shipping and returns" that answers ten questions produces chunks that match many questions a little and none of them well. The FAQ page guide explains where to find your customers' wording.

Before:
## Logistics

After:
## How long does UK delivery take?
## Can I change my delivery address after ordering?

2. Answer in the first sentence, and name the subject

Put the answer, and the thing it is about, in the first sentence under the heading. Chunk boundaries fall by size, not by heading, so a heading can end one chunk while its answer starts the next, as the rewrite example below shows.

Before:
## Can I return a sale item?
Great question. We know sales are exciting and we want you to love what you buy,
so we try to be flexible. In short: yes, within 30 days, for credit.

After:
## Can I return a sale item?
Yes. Fern Street sale items can be returned within 30 days of delivery
for store credit, not a refund.

3. Make every section self-contained

Delete "see above", "as mentioned" and "the same rules apply". PepoChat hands the model each matched chunk without its neighbours, so a pointer to another section points at text the model never sees. Anthropic's example of a chunk that fails alone is "The company's revenue grew by 3% over the previous quarter", which names neither the company nor the quarter. Repeat the fact, or link to the page that holds it.

Before:
Live plants follow the rules above. As mentioned, the same applies to gift cards.

After:
Live plants cannot be returned. Unused Fern Street gift cards can be returned
within 30 days of purchase for a full refund.

4. Name the product, plan and region every time

Replace "it", "this plan" and "the app" with the name. Each chunk is embedded from its own words, without the page title, so "it costs $12 a month" carries no trace of which product costs $12. Pick one name per product and plan and use it everywhere: a knowledge base that says "Team plan", "Teams" and "the mid tier" gives the model three things that may or may not be the same.

Before:
It's included on the middle tier but not on the cheaper one.

After:
Ledgerly API access is included on the Team plan and the Business plan,
not on the Starter plan.

5. Put conditions and exceptions next to the rule

Write who a rule applies to, when, and its exceptions in the same paragraph as the rule. An asterisk with a footnote at the bottom of the page ends up in a different chunk, so the model quotes the rule without its limits and the visitor hears "free returns" about a live plant.

Before:
Free returns within 30 days.*
(four sections later)
*Excludes live plants, sale items and orders outside the UK.

After:
Fern Street returns are free within 30 days of delivery for UK orders.
Live plants cannot be returned, sale items are refunded as store credit,
and orders outside the UK pay their own return postage.

6. Date anything that changes, and write prices as text

Add a "Last updated" line to every page that holds prices, limits or policies, and write "as of" into the sentences that quote them. The model cannot tell an old chunk from a new one unless the text says so. Write prices with the currency and the unit, because "4.95" in a chunk could be pounds, kilos or days.

Before:
Shipping: 4.95 (free over 50)

After:
As of 1 October 2026, Fern Street UK standard shipping costs £4.95 per order
and is free on orders over £50.

7. Write tables so every row stands alone

Use real tables rather than pictures of tables, and write each row so it makes sense without the header. HTML tables survive PepoChat's conversion as Markdown tables, but a long table is cut by size like any other text, and only the first chunk keeps the header row. We put an 18-row plan comparison under a short intro and ran it through PepoChat's code: the cut came after the "Audit log" row, and the second chunk held five rows of ticks and crosses with no plan names. A CSV file behaves the same way. Microsoft's chunking guide likewise suggests reformatting tables before they are chunked.

Before (the second chunk, exactly as stored):
| Single sign-on | ✗ | ✗ | ✓ |
| API access | ✗ | ✓ | ✓ |
| Phone support | ✗ | ✗ | ✓ |

After:
| Single sign-on | Ledgerly Business plan only |
| API access | Ledgerly Team and Business plans, not Starter |
| Phone support | Ledgerly Business plan only |

8. Put facts in text, not in screenshots

Never let an image be the only place a fact lives. Alt text is the short description an image carries for people who cannot see it, and in PepoChat an image on a web page contributes nothing but that alt text. Images inside Word files, text PDFs and Notion pages are not read, and an image uploaded on its own is only as good as a vision model's reading of it. The W3C's accessibility guidance on images of text already asks for real text wherever text can produce the same presentation. Write the facts in text, and give images alt text and captions that state what they show.

Before:
<img src="/img/pot-sizes.png" alt="sizes">

After:
<img src="/img/pot-sizes.png"
     alt="Fern Street pot sizes: small 12 cm, medium 17 cm, large 24 cm across the rim">
<p>Fern Street pots come in three sizes: small (12 cm), medium (17 cm)
and large (24 cm), measured across the rim.</p>

9. Keep answers out of scripts, tabs and button accordions

Put every answer in the HTML your server sends. PepoChat reads pages without running scripts, so an answer fetched by JavaScript when a tab or panel opens never arrives, while a panel hidden with CSS or the hidden attribute is still in the HTML and is read. Our test turned up two traps: PepoChat drops text inside a <button>, so an accordion whose questions are buttons arrives as answers with no questions, and it drops containers marked aria-hidden="true" entirely. The native <details> and <summary> elements keep both question and answer.

Before:
<h3><button aria-expanded="false">Can I return a sale item?</button></h3>
<div aria-hidden="true"><p>Yes, for store credit.</p></div>

After:
<details>
  <summary>Can I return a sale item?</summary>
  <p>Yes. Fern Street sale items can be returned within 30 days of delivery
  for store credit.</p>
</details>

10. Add an "also called" line for synonyms and old names

Under the heading, list the other words customers use for the same thing, plus any old product names. Embedding search matches meaning, which covers many paraphrases, but it cannot link your page to a feature's old name, your internal jargon or an error code unless those words appear in the text. PepoChat's search compares meaning only, with no separate keyword index, so put those words near the answer.

Before:
## Workspace deletion

After:
## How do I close my Ledgerly account?
Also called: delete my account, cancel my workspace, remove my data.
Ledgerly workspaces were called "books" before March 2026.

11. Use Q&A pairs for edge cases and quick fixes

Give one-line edge cases a Q&A pair instead of a page. A Q&A pair is a question stored together with its answer. In PepoChat a pair is indexed with the question written twice above the answer, so a short pair stays in one chunk with question and answer together, and pairs do not count as knowledge sources; a workspace holds 100 snippets and pairs on the Free plan and 1,000 on a paid plan, per the Q&A pair docs. Use them for edge cases and same-day fixes, then fix the page at your next review so the two agree.

Question: Do you ship live plants to the Channel Islands?
Answer: No. Fern Street does not ship live plants to Jersey or Guernsey.
Pots and tools ship there for £9.95 per order.

12. Keep one source of truth per fact

Keep each fact on one page and link to that page from everywhere else. A source of truth is the single place a fact is maintained. When two sources disagree, retrieval can return both, and the model may quote either or blend them; the guide to stopping chatbot hallucinations names contradictions and stale pages as the content problems behind most remaining wrong answers. Retire the copies as the sync section below describes.

Before:
returns-policy-2024.pdf     Returns accepted within 14 days
returns-policy-final.pdf    Returns accepted within 30 days
/help/returns               Returns accepted within 30 days

After:
/help/returns               Returns accepted within 30 days (the only copy)

Bad pattern vs better pattern: the 12 rules in one table

The table is the checklist version of the rules, with the reason each one matters to retrieval. Review a page against it: any bad pattern you find is a chunk that will mislead the agent or never be found.

Which file format works best for an AI chatbot?

A web page or a Markdown file written with the rules above works best, and a Q&A pair is best for a single fact. Word files and text PDFs work but lose structure in conversion, while scanned PDFs and images depend on a vision model's reading, so treat them as a last resort.

The table shows how PepoChat reads each format. The quality ratings are our judgment from those mechanics, not a benchmark, and other tools may parse PDFs and Word files with layout-aware models that keep more structure. The guide to training a chatbot on your website and PDFs covers adding each kind of source, and the Notion and Google Drive guide covers the two connectors.

How each format is read: PepoChat's ingestion code and documentation, checked 19 October 2026.

Our tests turned up two more traps. A Word table arrives as one cell per line ("Destination", "Return postage", "UK", "£3.95"), with nothing tying a price to its row. A PDF arrives one printed line at a time, so a chunk can start mid-sentence, and a two-column PDF that stores its text row by row across the page comes out with the columns interleaved.

A rewrite example: one messy policy page made chatbot-ready

Below is a typical shipping and returns section for Fern Street, a made-up plant shop, shown as HTML. We ran it through PepoChat's own conversion code on 19 October 2026, then did the same with a rewrite that follows the twelve rules.

<h2>Shipping</h2>
<p>We ship fast! Rates depend on where you are, see below.</p>
<img src="/img/rates-2025.png" alt="rates">
<p>Orders before the cut-off go out the same day.</p>
<h2>Returns</h2>
<p>Our policy is simple. You can send it back within 30 days, unless it's a live
plant, in which case the rules above apply. As mentioned, the same applies to gift cards.</p>
<h3><button aria-expanded="false">Can I return a sale item?</button></h3>
<div hidden><p>Yes, for store credit.</p></div>
<h3><button aria-expanded="false">What if my plant arrives damaged?</button></h3>
<div aria-hidden="true"><p>Send us a photo within 48 hours and we'll send a replacement.</p></div>

The agent stored this text from those sections, unedited:

## Shipping

We ship fast! Rates depend on where you are, see below.

rates

Orders before the cut-off go out the same day.

## Returns

Our policy is simple. You can send it back within 30 days, unless it's a live plant, in which case the rules above apply. As mentioned, the same applies to gift cards.

Yes, for store credit.

Count the losses. The shipping rates lived in a screenshot, so the agent received one word, "rates". Both accordion questions sat inside buttons and vanished: the sale-item answer survived as "Yes, for store credit" with nothing saying what it answers, and the damaged-plant answer, hidden with aria-hidden, disappeared. "The rules above" and "as mentioned" point nowhere. Asked about shipping to Ireland or a damaged plant, the agent has nothing to answer from, so the best outcome is an honest "I couldn't find that" and a handoff.

The rewrite, excerpted below, follows the rules: a dated opening line, one question per heading, answers that name Fern Street, rates in a real table and conditions inside each answer.

# Fern Street shipping and returns policy

Last updated: 1 October 2026. This policy covers orders shipped from Fern Street in Bristol, UK.

## How much does Fern Street shipping cost?

Fern Street UK standard shipping costs £4.95 and is free on orders over £50. Rates for other destinations are in the table below.

| Destination | Fern Street standard shipping | Delivery time |
| --- | --- | --- |
| UK mainland | £4.95, free over £50 | 2 to 3 working days |
| Ireland | £12.00 (no free threshold) | 4 to 6 working days |

## Can I return a Fern Street order?

Yes. Fern Street accepts returns of pots, tools and gift cards within 30 days of
delivery for a full refund. Live plants cannot be returned, but a live plant that
arrives damaged is replaced free of charge.

## What if my Fern Street plant arrives damaged?

Email a photo of the damaged plant to [email protected] within 48 hours of
delivery and Fern Street sends a free replacement. You do not need to return the damaged plant.

The full rewrite, six question headings and 1,867 characters of stored text, became two chunks of 963 and 903 characters. The cut fell between the heading "Can I return a Fern Street order?" and its answer, so the second chunk opens with "Yes. Fern Street accepts returns of pots, tools and gift cards within 30 days of delivery". Read alone, that sentence still says whose returns, which items and how long. Had it said "Yes, within 30 days", the chunk would match a returns question and leave the model guessing what it covers.

How do you keep your docs and your chatbot in sync?

Give every page an owner, change the source on the day a fact changes, and know how long each kind of source takes to reach the agent. Stale content is the quietest failure: nobody reports a wrong price, customers just act on it.

PepoChat refreshes each kind of source on its own schedule, and one of them does not clean up after itself. A website page that now returns an error keeps its last good text, because the weekly re-fetch and manual syncs skip a failed page instead of deleting it. Retiring a web page therefore takes two steps: remove or redirect it on your site, and delete its row on the Knowledge Base page.

Sync behaviour read from PepoChat's code and documentation on 19 October 2026.

Three habits help:

• Keep a change log. One line per change: date, page, old value, new value. When a price changes, search the knowledge base and the site for the old value, not just the page you remember.
• Test after every change. Ask the affected questions in PepoChat's Test the agent drawer, where chats are free and stay out of analytics.
• Read the escalations weekly. Every "I couldn't find that" in the team inbox is usually a missing section or one written in words customers do not use.

To put an AI assistant on the docs site itself, see adding AI chat to Docusaurus, GitBook, Mintlify or ReadMe.

What to do next

Start with the five pages behind your most common questions. Run the twelve rules over them, ask each question in a test chat before and after, and compare the answers. The self-service help center guide has article templates that already follow most of these rules, and the FAQ page guide shows how to collect the questions in your customers' words.

In PepoChat, the best practices checklist covers the same content habits, and published Help Center articles are mirrored into the knowledge base automatically. You can create a free workspace and test your rewritten pages in the drawer: every feature is on the free plan, which includes 200 AI replies a month and 5 knowledge sources, with no credit card.