For fifteen years, getting documentation out of a development team was a fight. You asked for it in review, you put it in the backlog, it never came. The README was three years old, the architecture diagram described a system that had been refactored twice since, and everything that mattered lived in the heads of two people you had to catch between meetings.

That problem is solved. For a little over a year now I’ve been seeing — at my clients as much as in my own projects — documentation that is complete, well structured, up to date with the latest overhaul. Pages and pages of it. Often more than there is code to read.

And it’s worse.

We mistook volume for knowledge#

There is nothing accidental about it. When the cost of producing something collapses, we don’t produce the same quantity more cheaply: we produce vastly more of it. That was true of coal, of bandwidth, and it is true of the documentation page. Writing twenty pages costs nothing now, so we write twenty pages.

Except that what fills those pages was, most of the time, already in the code. A comment announcing that the getUserById function retrieves a user by their identifier teaches nobody anything: it paraphrases the signature. Five immaculately formatted paragraphs that say neither what the module is for, nor the constraints it was written under, nor where the traps are, teach nothing either. And the why — why this cache, why this trade-off, which alternative was rejected and on what grounds — is invariably missing. It was never in the code. It’s in people’s heads.

I have a simple, slightly brutal test: delete the page. If nobody notices within six months, there was nothing in it.

For twenty years we have been told that late documentation is a motivation problem. It wasn’t, it was a tooling problem. AI fixed the tooling — and demonstrated that the issue had never been either one.

The real cost isn’t the time wasted, it’s the trust#

A developer opens a page and finds a method that doesn’t exist. A configuration parameter invented out of thin air, an option that was never implemented. They lose half an hour chasing a ghost. That isn’t the serious part.

The serious part is what they do next: they stop trusting the documentation. Not that page — all of the documentation, including the eighty percent that was accurate. And that kind of trust doesn’t come back by decree.

The loop then closes neatly. We document so that information circulates; unverifiable documentation produces the exact opposite. Nobody reads anymore, and we go back to asking two people between meetings. Back to square one, with a stock of pages to maintain thrown in. Every useless page has raised the noise level by one notch.

The figures available don’t cover documentation but generated work content in general, and they will do. Researchers at BetterUp Labs and Stanford’s Social Media Lab put a name to content that has the appearance of serious work without the substance: workslop. Their survey puts it at one hour and fifty-six minutes on average to sort out each incident, and above all a 42% drop in the trust extended to whoever produced it. These figures are self-reported and their methodology has been challenged; the order of magnitude, though, matches what I observe.

On the production side the asymmetry speaks louder still: generating forty pages takes an hour, reviewing them seriously takes a week. Verifying a plausible claim costs more than writing it yourself. The cost hasn’t disappeared — it has moved, and it has grown.

That leaves the question of why nothing gets filtered out. The answer is unpleasant: our safeguards aren’t looking there. A code review hunts for errors in code. Nobody re-reads comments, even when they are wrong. That was already true before AI, except there were ten times fewer of them.

Who are we writing for, exactly?#

There is an irony in all this that I find delicious. This documentation nobody reads anymore, we do read it — with an AI. We ask an agent to summarize the pages an agent wrote.

This is no longer anecdotal: according to figures published by GitBook, 41% of requests to documentation pages now come from agents. A standard was even born for it, llms.txt, proposed in 2024: a file that tells models what to read in your documentation. Some platforms go further and offer tags for content reserved for agents, which humans will never see.

And what do the writing guides accompanying this movement recommend? Lists rather than walls of text, short paragraphs, no filler. Exactly what we should have been doing for our colleagues all along. Except that this time, it’s for the machine’s comfort.

Some draw the opposite conclusion from mine: since agents consume documentation, producing it en masse would become an advantage. I don’t believe that for a second. An agent doesn’t compensate for an absence of intent, it propagates it — faster, and at greater scale. You aren’t building a knowledge base, you are training a machine to repeat your own approximations.

The TL;DR nobody can write for me#

Here is what I do now, and it comes down to one rule. Before generating a single line of documentation, I write the header myself: a TL;DR of three or four sentences, in my own words, unassisted.

It sounds trivial. It changes three things.

It gives direction. A model asked to document a module produces an inventory; the same model, handed the intent in three sentences first, produces text that goes somewhere.

It surfaces my own mistakes. Summarizing a component in your own words means discovering that you had misread a condition, or that you can’t explain a choice you thought you had mastered. Those ten minutes of discomfort are the best return on investment of the day.

It makes the page usable as is. A colleague reads four sentences written by a human, understands, and doesn’t need to have the rest summarized by an agent.

A word on verbosity, because my first reaction was naive: I used to ask in my prompts to be concise, to avoid walls of text. That is a hack. Everyone with their own prompt, everyone with their own style, forty pages in forty voices. The constraint has to be structural — a style guide and templates injected into every generation, in one place for everyone. And for the decisions that shape a system, there is a sturdier format than the TL;DR, one that is twenty years old and didn’t wait for AI: the ADR, one page per decision, context, decision, consequences.

The noise floor#

In audio, the noise floor is the level of background noise below which a signal becomes undetectable. It erases nothing: it drowns. We haven’t degraded our documentation, we have raised the floor until the good stuff became impossible to find in the middle of the rest.

AI doesn’t replace expertise, it amplifies it — in both directions. Those four sentences I write by hand aren’t the chore left over once automation is done: they are the only place where I still bring something. Everything else, the machine does better than me, faster, and for next to nothing.

Everything else is also what makes the noise.

Sources#