Writing Docs for Two Readers: Humans and AI Agents

Your documentation now has a second reader, and it reads nothing like the first. Alongside the human skimming for an answer, an LLM or agent is pulling fragments of your docs to answer a question or drive a workflow, and the two readers want opposite things.

A person reads top to bottom, follows a screenshot, and fills gaps from context. An agent pulls one isolated chunk, ignores the layout entirely, cannot see the screenshot, and falls apart when the real meaning was in a diagram or an unstated assumption. The same page that works fine for a human can hand an agent a confidently wrong answer.

This talk shows what actually changes when you write for both. It covers structuring content so a retrieval system returns a correct, self-contained answer, what conventions like llms.txt do, and exposing docs through the Model Context Protocol so an agent queries them at runtime instead of scraping a rendered page. It is also honest about the cost: optimizing for machines can flatten the voice and context that make docs good for humans, and some advice going around right now trades real quality for retrieval scores.

What this talk covers:

• How an agent reads your docs differently from a human, shown concretely

• Structuring content for self-contained retrieval without dumbing it down

• What llms.txt and MCP actually solve, and what they do not

• A live look at the same docs page answered well versus badly by an agent

• A page-by-page rule for when to optimize for the machine and when to refuse

This is for anyone maintaining docs for an open source project who has noticed AI assistants quoting those docs and wants them to be right.

• Audit one of your own doc pages for how an agent would actually read it

• Restructure a page so that a retrieval system returns a complete, correct chunk

• Decide what belongs in llms.txt or an MCP server versus the human-facing page

• Tell the difference between machine-readability that helps and advice that just wrecks your docs