The Second Reader

Reflections | Business Evolution

References: 10x Speed, Zero Structure

Documentation was written for the next person who'd need to understand a decision. Increasingly, that person isn't a person.

In my last note I mentioned an asterisk almost in passing — that LLMs are getting fast at learning a codebase's own patterns, and that the documentation itself is changing shape because of it. I want to sit with that properly, because I think it's a bigger shift than a footnote.

Documentation never existed for its own sake. It existed so that someone who wasn't in the room when a decision was made could still understand why.

That someone was always assumed to be human. A new hire. A teammate six months from now who's forgotten the context. You, eighteen months later, looking at your own code and wondering what you were thinking.

Everything about how documentation got written followed from that assumption — prose, narrative, "here's the story of why we did it this way." Written to be read once, slowly, by someone building a mental model from scratch.

That assumption doesn't hold anymore, at least not as the default.

On the team I'm on now, the first reader of most documentation is an agent — a skill file, an MD file, a set of instructions sitting in the repo that gets loaded before a human ever opens the same file. The human reader still exists. They're just not first in line anymore.

This isn't a small formatting difference. A human wants narrative — context, reasoning, the story of a decision. An agent wants structure — clear, scoped, unambiguous instructions it can act on without inferring intent from tone. Writing for both at once tends to produce documentation that serves neither well.

The upside is real, not just theoretical.

Documentation written as structured context — a skill file describing how a team names things, where decisions live, what patterns to follow — gets produced almost as a byproduct of working with these tools at all. Nobody has to remember to write it up afterward. It's there because the agent needed it to do the work in the first place.

That inverts the old failure mode. Documentation used to lapse because writing it was a separate, deprioritised task. When it's load-bearing for the tool you're using every day, it stops being optional in the same way.

I don't want to overstate this.

A model inferring intent from patterns can still infer wrong — the same way a new hire reading old code can draw the wrong conclusion from it. Structured context tells you what the pattern is. It doesn't always carry why the pattern exists, or which parts of it are load-bearing versus incidental.

That "why" is still a fundamentally human thing to capture. The difference is where it needs to live and how much of it there needs to be. Less narrative prose explaining the obvious, more precision on the judgment calls that actually matter — the decisions a pattern-matcher would get wrong by default.

The practical shift is smaller than it sounds: before writing anything down, ask who's actually going to read this first.

If it's an agent, write structure — scoped, explicit, built to be acted on. If it's a human trying to understand a judgment call, write the story. Most documentation probably needs both, in the right order, rather than one bloated document trying to be both at once.

Documentation isn't becoming less important because AI can infer more. It's becoming more important, for a different reader, in a format most teams haven't fully adjusted to yet.