We Write Documentation Nobody Reads (and It's Never Been More Useful)

Every company I’ve known has a documentation graveyard. A Confluence with three hundred pages nobody has opened in two years. A Notion that started out organized and became a dumping ground. A Drive folder with four versions of the same document and none of them marked as the right one.

The diagnosis is always the same: lack of discipline. The team doesn’t write, doesn’t maintain, doesn’t read. And the proposed fix is always the same too: a new process, a named owner, a quarterly review ritual. It never holds for long.

I spent years accepting that diagnosis. Today I think it was wrong from the start. It wasn’t discipline. It was two different problems, neither of them about character, and both of them collapsed in the last few years almost without us noticing.

Before I go on, a warning: this is not a recipe. I’ll come back to that at the end.

Why documentation always rotted

The first problem is that the reader was bad. And I’m not putting anyone down here. I am that reader.

Humans skim documentation. We read the part that confirms what we already thought. We skip the section that looks bureaucratic. We read it once, during onboarding, and never come back. When the question shows up six months later, we ask on Slack instead of searching, because asking is faster than digging.

That destroys the economics of the whole thing. Writing good documentation is expensive: it requires someone who understands the subject to stop doing something else and spend hours turning tacit knowledge into precise text. And the consumption rate of that text was near zero. High cost, low use. Any leader who ran that math once learned not to prioritize documentation, and they were right within that logic.

The second problem is that the medium had no defenses at all.

Business rules always lived in Confluence, Notion, Google Docs, spreadsheets. Think about what’s missing in those places: no branches, no diff you can actually read, no mandatory review before something takes effect, no legible history, nobody approving. Anyone edits anything at any time, and no trace is left of who changed what or why.

Now compare that to code. Code doesn’t rot the same way. And it’s not because developers are more disciplined than product people. It’s because code lives somewhere that has pull requests, review, history, and blame. The environment enforces a quality that no individual would sustain alone.

Documentation never had any of that. We blamed people for a defect in the medium.

We swapped the reader

The first change is the one nobody says out loud, because it sounds small and isn’t.

On the teams where I’m trying this path, the developer doesn’t read the business-rules documentation. Their AI agent does.

And the agent is the reader documentation always deserved and never had. It reads with a consistency no human sustains: every time, from scratch, without half-remembering a version from three months ago. It doesn’t skip a paragraph for being boring, doesn’t assume it already knows, doesn’t confuse this project with the last one, doesn’t get lazy on a Friday afternoon.

But I’d be selling this too easily if I said it reads everything. Long context degrades, the middle of a document gets less attention than the edges, and retrieval systems hand over excerpts, not the whole text. The agent skims too. The difference is that it doesn’t tell you. A human who skipped a section at least knows they skipped it. That doesn’t cancel the trade, but it changes what the trade is: I didn’t get a perfect reader, I got a tireless one. Those are different things, and the second one is already a lot.

Notice what that does to the math. The cost of writing stays exactly the same. Consumption went from near zero to its practical ceiling: automatic, on every task, depending on nobody’s willingness. The same documentation that used to be waste became the highest-return input in engineering without a single line of it having to change. What changed was who’s on the other side.

And human reading didn’t disappear. It moved up and concentrated. Before, ten people each read one document badly. Now a few people (product and project leadership) read it well, once, at the moment of writing and approving. Their reading gets replicated with fidelity across every workstream, without degrading along the way.

We swapped the medium

The second change is simpler to describe and just as decisive: business rules left the text editor and moved into the repository.

Every rule change opens a pull request. Someone reviews it. Someone approves it. It’s on record who proposed it, who accepted it, and when. And because it’s a repository, each rule can carry where it came from: the decision that produced it, what was considered and discarded along the way.

That solves the problem no quarterly review ritual ever solved: business knowledge got the same tracking system code has always had.

I’d rather not stretch the analogy, because it’s seductive and misleading. What protects code isn’t the pull request ritual. It’s the compiler, the tests, the type system, and feedback from production. Prose has none of those four, and reviewing text turns into a rubber stamp faster than reviewing code does. What I gained was history, authorship, and traceability, which is a lot and didn’t exist before. Verification I did not gain.

One side effect I didn’t see coming: you can run blame on a business rule. You can point to the exact moment the company changed its mind about its own domain, who proposed the change, and what was known at the time. Six months later, when someone asks “why does this work this way?”, the answer doesn’t depend on the memory of whoever was in the room.

None of this is my invention, and that’s worth saying. Recording architecture decisions in a repository, treating documentation as code, and writing specs in an executable format are practices with more than a decade behind them. What changed isn’t the technique for storing things. It’s who started reading what we store.

The most expensive review is no longer the code review

Here’s the consequence that most changed how I think as a leader.

One wrong line of code breaks one feature. Someone files a ticket, someone fixes it, done.

One wrong rule breaks the entire class of problems. Because from the moment it’s approved, every agent, in every workstream, will read it and reproduce it with perfect fidelity. The agent doesn’t make mistakes reading a bad rule. It executes the bad rule precisely, in five places at once, and the result comes out looking entirely correct.

The quality control point moved addresses. The most expensive review in my engineering org today isn’t the code diff. It’s the one that happens earlier, when someone approves a rule.

That also changed what the product function actually is. Writing a ticket for a human to interpret is one thing. Writing the substrate that will govern how the whole system behaves is something else entirely: far more leverage, and a far larger blast radius.

And there’s something elegant in this: the spec didn’t die, it changed frequency. The twenty-page document approved once before the project started was spec as an event, and that’s exactly why it was bad, because it got almost everything wrong and nobody went back to fix it. What exists now is spec as a flow: small, frequent changes, each one with a reviewer. Same function, opposite cadence.

The prototype is still the plan (but now it starts out informed)

Something I learned early and never unlearned: the best plan is a prototype. No spec written before the product exists has ever described the product that actually shipped. You only find out what the thing is by building a scrappy version of it.

That still holds. What changed is where the prototype starts from.

An invented example, so I’m not using anything from my own work. Imagine a marketplace with a rule about returns past the deadline. It used to be a single rule: past the deadline, the seller decides whether to accept. After some discussion, it became two:

• If the product comes from the seller’s own inventory, they can grant an exception.
• If it came from the platform’s shared catalog, there is no local exception, and the option doesn’t even appear on screen.

Notice what that rule actually encodes. It isn’t a technical constraint. It’s a fact about where authority lives: you rule what’s yours, and you don’t rule what belongs to the network. That’s written nowhere in the code, because it isn’t a property of the code. It’s an organizational decision.

An agent building the prototype without that rule will get one of the two paths right and the other wrong. Worse: it’ll get it wrong plausibly, with a clean screen and a coherent flow, and whoever reviews it will have no reason to be suspicious.

The same prototype, with the domain rules loaded, comes out as something else. Same time window, same effort. Without context it’s an expensive guess. With context it’s a proposal.

That’s what dissolves the handoff from one person to another. If the guideline is written down and machine-readable, I don’t need someone translating business into developer. I open workstreams and each person advances against the same reference. Nobody hands anything off to anybody.

The part almost nobody writes down

If I could carry one single thing from this text into another company, it would be this.

All corporate documentation is a monument to certainty. It records what’s already known and pretends the rest doesn’t exist. But the interesting part of any complex domain is precisely the part nobody has decided yet: the ambiguity that shows up in the third meeting, disappears in the fourth, and comes back to bite six months later as a bug nobody understands.

What started making the most difference on my teams wasn’t documenting what’s decided. It was keeping an explicit register of what isn’t: the open decision, what depends on it, and who owes the answer.

That changes the agent’s behavior in a way I didn’t expect. An agent that finds “this hasn’t been decided yet, the owner is so-and-so” stops and asks. An agent that finds nothing fills the gap on its own, confidently, and moves on. The superpower isn’t the agent knowing the rules. It’s the agent knowing where the rules run out.

And there’s a purely managerial gain here, nothing to do with AI: when what’s open becomes a list with owners, uncertainty stops circulating as a diffuse feeling in the team and turns into addressable work. You can watch, in the history, the questions being retired one by one. It’s the organization converging on its own domain, with dates and names attached.

The loose ends I haven’t solved

I’m not going to end this pretending it’s all closed.

The first is decay. Nothing in this system kills an old rule. The rule that was right in January and became wrong in July because the business changed has nobody to take it down. Writing errors get caught at approval, because there’s a reviewer, that’s what they’re for. Decay has no alarm. And decay is worse than error, because the rule sits there carrying all the authority of something that was reviewed and approved, being read with perfect fidelity by every agent, long after it stopped being true.

The instrument to detect this exists: the repository knows exactly when each rule was last touched, and a rule untouched for a long time in a domain that has moved is a measurable signal. What doesn’t exist yet is the watch. Nobody gets woken up for it.

If that problem hasn’t bitten me yet, it’s a matter of how long I’ve been running this, not proof that it’s solved.

The second is what happens to the people who no longer read. If a developer doesn’t need to read the business rules, where does their domain judgment come from three years out? A good share of what I know about education I learned by reading boring things that weren’t my job. Concentrating the reading in a few people solves fidelity and creates a bottleneck: the same heads approving everything, and a team that executes a domain it doesn’t know extremely well. I don’t yet know whether that trade pays off.

The third is security, and it’s the one that shows up least in this conversation. A repository of rules that agents read and execute is, in practice, a policy engine without any of a policy engine’s guarantees. It’s an injection surface, because text that goes in becomes behavior, and it’s an audit question someone in risk will ask before I do. In a regulated sector, and education is one, that question has a mandatory answer. I don’t have mine yet.

What I take from this

I’m not prescribing anything here. Today I have teams working in different formats, on purpose. The ground is moving too fast for me to standardize an entire engineering org on a hypothesis I haven’t finished validating. And anyone claiming with great conviction that they’ve figured out the right way to work with AI in 2026 is, at best, being optimistic.

What I have is a bet that’s paying off so far, and a reading of why.

And “paying off” here is an impression, not a measurement. I didn’t set up a control group, I don’t have a clean before-and-after number, and there’s serious research showing that the perceived gain from AI tends to be much larger than the real one. In a controlled 2025 study, experienced developers got slower with the tools while swearing they had gotten faster. Let it be on record that I might be exactly the subject of that bias.

Documentation was never a bad idea. It was a good idea with two structural defects: we were writing for a reader who didn’t read, and storing it somewhere with no defenses. Both defects fell: one because the reader changed, the other because we finally changed the medium. The work of writing costs exactly as much as it always did. What changed was the return.

And if I’m right about this, the skill that becomes scarce isn’t writing code. It’s being able to look at an operation you know well and turn what “everybody knows” into text precise enough for a machine to act on. That’s still human work. And it just became a lot more valuable.

---

If this topic interests you, I’d love to exchange ideas. Find me on LinkedIn.