The Documentation Problem Agents Create

Documentation has two audiences now, and they need different things. That's the change, and it's more consequential than "agents can write docs" — which is the version usually discussed and the less useful one.

The two readers

A human reads documentation to build a mental model. They want orientation, the reasoning behind decisions, what to watch out for, how pieces relate. They skim, they follow links, and they bring context.

An agent reads documentation as retrieved fragments. It gets a chunk, not the document. It has no orientation, doesn't skim, and can't tell that a passage is outdated unless the passage says so.

→ Which means the properties that make documentation good for one are not the properties that make it good for the other, and a single corpus optimized for humans serves agents poorly.

What agents need that humans don't

Self-contained statements. A passage saying "this means the limit is 60" is fine for a human reading in order and useless as a retrieved chunk.

Explicit dates and versions. Humans infer currency from context — the page looks old, the screenshot is from an old version. An agent can't, and will present a three-year-old claim as current.

Stated units and formats. "Timeout: 30" is unambiguous to someone who knows the system.

Explicit exclusions and edge cases. The business rule everyone knows and nobody wrote — that cancelled orders retain their total but shouldn't be summed for revenue. A human knows; an agent produces a wrong number confidently.

A designated source of record. When three documents disagree, humans know which one counts. Agents don't.

⚠️ The problem generation creates

Cheap documentation generation produces more documentation, and volume is not the constraint — accuracy and findability are. More pages that nobody maintains means more retrieved chunks that are subtly wrong, and the agent surfaces them faithfully.

The specific failure: generated documentation that describes what the code does. It's accurate at the moment of writing, drifts immediately, and reads as authoritative. Meanwhile the thing worth documenting — why it's like this — isn't derivable from the code and doesn't get generated.

Documentation that restates the code is negative value once it drifts, because it's a confident wrong answer with an authoritative source attached.

✅ What to do

Document why, not what. The reasoning, the constraints, the rejected alternatives, the things that will surprise someone. This is what agents can't generate and what nobody can reconstruct later.

Date everything, visibly. Every page and, where it matters, every claim.

Name the source of record for each kind of fact.

Write self-contained sections with the context stated, so retrieval works.

State the business rules explicitly, especially the ones everyone knows. These are the highest-value sentences in your corpus for an agent, and the least likely to exist.

Delete aggressively. ✅ A smaller accurate corpus beats a larger comprehensive one, because retrieval quality is what determines answer quality. This is the recommendation people resist most and it's the one with the largest effect.

Run a contradiction check. Where documentation disagrees with code or with itself — an agent can do this mechanically, and it's the highest-value thing to point one at.

💡 The corpus-hygiene reframe

For agent-facing documentation, treat it as a data quality problem rather than a writing problem. The properties that matter — accuracy, currency, self-containment, non-contradiction, clear authority — are data properties.

Which suggests the practices: an owner, a freshness policy, automated contradiction checking, and a bias toward deletion. Not the practices of a documentation project, and closer to the practices of a maintained dataset.

The takeaway

Documentation now serves humans building models and agents retrieving fragments, and the two need different things. Write the why, since that's what can't be generated and can't be reconstructed. Date everything, name the source of record, state the rules everyone knows, and keep sections self-contained. Then treat the agent-facing corpus as data — owned, checked for contradictions, and aggressively pruned — because for retrieval, a smaller accurate corpus beats a larger comprehensive one every time.