Agent Readiness: Writing Docs Machines Can Actually Use

For years we wrote documentation for one audience: people. That assumption is quietly breaking. The fastest-growing reader of your docs may not be a human at all — it’s an agent retrieving, parsing, and acting on what you wrote.

Agent readiness is how well your documentation survives that trip. Can a model find the right page, extract the right step, and not hallucinate the gaps you left implicit? A doc that a careful engineer can follow may still fail an agent, because the agent can’t read between the lines.

A few things that move the needle:

• State the obvious. Implicit prerequisites are invisible to a retriever.
• Keep one fact in one place. Contradictions across pages poison retrieval.
• Structure over prose. Headings, lists, and stable anchors are machine-legible.

This is where my media-tech background keeps the topic concrete: shipping DRM and streaming docs in a hard domain taught me exactly how expensive an ambiguous instruction is. Agents just raise the stakes.

More to come as I experiment.