When a developer asks ChatGPT or Perplexity how to do something with your API, the model retrieves a handful of pages, picks one or two to cite, and writes the answer. The cited page gets a small icon next to the response and a link the user is likely to click. The pages that didn't get cited don't show up at all.
Which page wins is rarely about which one is most thorough. It's about which one looks, to the model, most like a clean answer to the question.
What an answer with a citation actually looks like
Here's roughly the shape a model produces when it has a good source to cite:
The model didn't write that from scratch. It pulled it from a single page that already answered the question in roughly those terms. The citation rewards pages that lined themselves up to be quoted.
The pattern AI engines reward
A page is more likely to be the one cited when:
- The section heading restates the question. "Authenticating to the Acme API" beats "Authentication." A reader skimming might forgive the shorter heading. A retrieval system reading section-by-section won't make the connection as reliably.
- The first sentence under the heading is the answer. Not background. Not "before we get into authentication, let's discuss tokens." Just the answer. The model usually quotes from the first one or two sentences of a retrieved chunk.
- The section is self-contained. Anyone landing in the middle of the page can read just that section and understand it. No "as mentioned above," no implicit subject, no required context from the page intro.
- Important constraints are repeated in place. If the endpoint requires admin auth, the section about that endpoint says so, instead of relying on a banner at the top of the page.
These are the same patterns that help with doc pages surviving chunking. They're also the patterns that help a human who lands on a page through a search anchor.
What kills a citation
The opposite patterns are reliable citation-killers:
- Forward references. "See the previous section." The chunk doesn't include the previous section. The reference dies.
- Marketing intros. A section that opens with "We believe authentication should be simple" before getting to the answer. The model skips ahead, and the snippet it pulls is the marketing line.
- Page-level disclaimers. A note at the top of the page that says "this entire page assumes you're on Pro plan." The model retrieved a section in the middle. The plan caveat is invisible.
- Concept first, code last. A page that explains the theory of auth before showing the curl command. Many models will give up on the page before reaching the example.
Any one of these is enough to push a model toward a different source that ranks lower for relevance but higher for clarity.
What this means for your docs
Structuring for citation is mostly the same as structuring for any reader who's in a hurry. The difference is that AI engines never read past the chunk they retrieved. There's no skimming back up for context. If the section doesn't stand alone, it's not getting cited.
A few things help on the infrastructure side. A clean OpenAPI spec gives engines a structured map of your API to anchor against. An llms.txt file tells AI tools where to look first; we wrote about how to think about it in llms.txt for APIs. An MCP server goes one step further and exposes your docs in a format AI clients can call directly. For a wider take on engine retrieval behavior, see Optimizing for ChatGPT, Claude, and Perplexity.
How ReadMe puts this together
ReadMe generates llms.txt and a project MCP server automatically from your docs, so the AI-readable surface stays in sync with what you publish. The Linter and Docs Audit catch the structural patterns that kill citations: pages with forward references, sections that don't restate their subject, intros that bury the answer. The AI agent can rewrite a section to be self-contained in one prompt.
The point isn't to write for engines instead of humans. It's that the writing that wins citations is also the writing that helps a developer skim. If you want to see how this fits with the rest of the AI tooling, see Team Up with AI to Build Docs. To set it up on your own docs, start a ReadMe project or talk to our team.
