Your documentation has a new reader

Documentation has always had a measurable readership, and it's always been terrible. A new engineer reads it once, in week one, when they've got no context to judge any of it with. After that almost nobody opens it again, because by month two you ask a person instead. That was the honest lifecycle, and it's why docs rotted so quietly: the cost of them being wrong landed months later, on someone with no standing to complain.

That readership has changed, and not gradually. In a codebase an agent is working in, the docs get read on every single task. Not skimmed once and abandoned. Read, cited, acted on, dozens of times a day, by something that'll do exactly what they say.

It's the biggest change to the economics of documentation in my career, and most of the conversation about it is stuck on the wrong half. The interesting part isn't that AI can write your docs now. It's that AI reads them, which means a doc site has quietly turned into an interface, and interfaces play by different rules than prose does.

What changes when the reader is a machine

A human reader is a forgiving parser. They resolve ambiguity from context. They notice when a page smells out of date and go check the code instead. Every one of those habits is silent repair work on your documentation, and you've been getting it free for years.

An agent does none of that repair. It reads what's written and treats it as current. Ambiguity a person would have resolved correctly becomes a coin flip. A stale sentence a person would have squinted at and distrusted becomes a confident wrong action three steps later.

So what counts as good documentation has shifted. Not reversed. Shifted, and towards things that used to be matters of taste:

Explicit over narrative. "As described above, the ledger consumes these events" is fine for someone reading top to bottom. It's useless to something that retrieved this one section and nothing else. State the fact where it gets used, even when that means saying it twice.

Addressable and stable. Agents cite sections and come back to them later. Heading anchors that shift when you reword a title break every reference anyone stored. Anchors are an API contract now, and they deserve the same reluctance to break.

Available as source. Rendered HTML is for humans. The markdown underneath is better for everything else, and on a static site serving both costs you nothing. Same goes for a root llms.txt, the emerging convention for pointing a model at what matters:

# Ledger Service
> Double-entry ledger. Owns account balances. Publishes settlement events.

## Docs
- [Architecture](/architecture.md): bounded context, ownership, what it does not own
- [Events](/events.md): published and consumed contracts, with versioning rules
- [API](/api.md): HTTP surface, auth, idempotency semantics

There's a Starlight plugin that'll emit that for you, and if you'd rather not take the dependency it's a short integration to write yourself.

Negative space, stated out loud. Almost nobody does this one and it matters more than everything above it. Write down what the service doesn't own, what it doesn't publish, what it deliberately refuses to handle. A gap in documentation doesn't read as a gap. It reads as an invitation, and the model fills it with the most plausible thing, which is often a design you rejected two years ago for good reasons.

The generation half

This is where the enthusiasm is, and it's warranted. Point a model at a real codebase, ask for a documentation site, and you get something genuinely usable in hours. Service boundaries, message contracts, API signatures, the call graph as it actually is rather than as the wiki said in 2023. It's very good at this, because all of it is derivable from code that's sitting right there.

Astro Starlight is a good target for the output: static, markdown-native, and the source files are the artifact rather than a database you have to export from. One body of content, pleasant for people, trivially consumable by everything else.

Two limits, though, and the first one outweighs the enthusiasm.

The second limit is sharper. A model can derive what the code does. It can't derive why. It'll tell you the billing service publishes InvoiceSettled and not PaymentReceived. It won't tell you that you tried the second one, found it coupled two teams' deploy schedules together, and pulled it back out. That decision isn't in the source. Neither is the option you rejected, or the constraint that forced your hand.

Which is the useful way round to think about it. Collapsing the cost of the what layer doesn't make documentation a solved problem. It clears away the tedious half and leaves the half that was always worth reading, and now there's no excuse for skipping it.

Two readers, one discipline

What I didn't expect is that writing for the second reader improves the docs for the first.

Every property above (say it explicitly, say it where it's used, name what you don't own, keep the anchors stable) is something a good technical writer would have told you to do anyway. They were just easy to skip, because a human reader papers over the gap and you never find out. The agent papers over nothing. It fails visibly, and it fails in a way you can trace straight back to the sentence that caused it.

That's the best feedback loop documentation has ever had. Docs used to fail silently, months later, for someone who assumed the problem was them. Now they fail in front of you, on a Tuesday, in a way you can fix.