There’s a quiet assumption baked into most technical documentation: that someone will sit down and read it. Start at the top, work through to the bottom, arrive at the other end understanding the system. We write as if we’re authoring a textbook, taking a reader on a careful journey from ignorance to competence.

Nobody reads documentation like that. They never really did, and in the age of AI they definitely don’t. So it’s worth asking what documentation is actually for, and whether the way we write it still matches the way it gets used.

Docs Are Not a Journey

A good technical textbook is a story. It has an arc. It introduces a concept, builds on it, and each chapter earns the next. The author controls the order you encounter ideas because the order is the point. That’s pedagogy, and it’s hard, valuable work.

Repository documentation is not that. Nobody opens your service’s README to be taken on a journey. They arrive with a question, mid-task, mildly annoyed, and they want the answer and nothing else. The moment you make them read three paragraphs of narrative to extract one fact, you’ve failed the actual job.

The mistake is conflating the two. When you write reference material as if it were a story, you get prose that buries facts inside sentences, context that has to be read linearly to make sense, and a document that’s simultaneously too long to skim and too shallow to teach. It’s the worst of both. A reference exists to get out of the reader’s way. Optimise for the person who arrives already knowing what they want and just needs you to confirm it fast.

Write What Doesn’t Rot

Here’s the uncomfortable truth about technical documentation: most of it is wrong within months. Not because anyone was careless, but because the thing it describes kept moving and the words didn’t.

Some facts rot faster than others. The exact flags for a third-party CLI, the current version of a dependency, the precise shape of an API response, these are volatile by nature. The instant you copy them into your docs you’ve created a second source of truth that will drift from the first. Every one of those copied facts is a small debt that comes due the day someone trusts it and gets burned.

The reasoning behind a decision rots far more slowly. Why we chose this queue over that one. Why the retry logic backs off the way it does. Why this seemingly redundant step exists. That context is durable because it’s tied to constraints and trade-offs, not to a version number. It’s also the part nobody can reconstruct from reading the code, which makes it the part most worth writing down.

This is what Architecture Decision Records get right. An ADR captures a decision, its context, the options weighed, and why you landed where you did, including the roads you didn’t take. That last part is the one thing reading the current code can never tell you: the code shows what won, never what was rejected or why. And a decision record ages unusually well, because it’s a snapshot of one moment’s reasoning rather than a description of a moving system. It stays true even as everything it once described changes underneath it.

So invert the usual priorities. Spend your words on the thinking, and offload the volatile facts to wherever they already live authoritatively. Don’t transcribe the third-party CLI’s arguments, link to its help output and explain why you’re calling it this way. Don’t paste the config schema, point at it and document the two settings that actually matter and the reasoning behind their values. The rule of thumb: if a fact has an authoritative source somewhere else, reference it rather than copy it. Copy only what you own, and even then, prefer explaining the why over restating the what.

This has a nice side effect. Docs that carry reasoning instead of transcribed facts go stale far more gracefully. When the reasoning is wrong, it’s usually interestingly wrong, a sign the constraints changed, which is exactly the moment you want someone to stop and think rather than blindly follow stale instructions.

The Reader Isn’t Human Anymore

The bigger shift is who, or what, is doing the reading.

Increasingly, people don’t read documentation. They point a model at it and ask a question. The doc’s job is no longer to be absorbed by a human over coffee, it’s to be retrieved, chunked, and reasoned over by a machine acting on that human’s behalf. That changes what good looks like.

Writing for retrieval means writing in self-contained units. A model pulling one section into context can’t rely on setup from six paragraphs earlier the way a linear reader could. Each chunk should stand on its own: state its assumptions, name its subject explicitly instead of leaning on “it” and “this”, and avoid meaning that only emerges from reading in order. The clever narrative callback that delights a human reader is invisible to a retrieval system that only grabbed the paragraph it matched. Ambiguity that a person resolves from context becomes a coin flip for a model.

This is not a betrayal of human readers. Precise, self-contained, skimmable writing serves the annoyed human mid-task better too. Optimising for the machine and optimising for the impatient human turn out to point in the same direction.

And sometimes the honest answer is that prose is the wrong medium entirely. If what you’re documenting is really a set of actions a model should take, a well-built MCP server can carry that intent better than any amount of writing, because it’s executable rather than descriptive. Documentation tells the model what it could do. A tool lets it do the thing and get a result back. When you find yourself writing paragraph after paragraph explaining how to drive an interface, that’s often a signal the interface itself should be the documentation.

Questions Worth Asking Before You Write

The most useful framework here isn’t new and isn’t mine. It’s Diátaxis, developed by Daniele Procida and now used by Django, Canonical, Cloudflare and others. Its core claim is that there are four distinct kinds of documentation, and most bad docs are bad because they try to be several at once:

  • Tutorial, learning-oriented. This is the story, the hand-held journey, for someone with no context yet.
  • How-to guide, task-oriented. A recipe for someone who already knows what they want and needs the steps.
  • Reference, information-oriented. Dry, accurate, complete. The thing you look a fact up in.
  • Explanation, understanding-oriented. The why: background, trade-offs, the reasoning that outlives the facts.

Most repository docs are reference and explanation wearing a trenchcoat. They fail when they smuggle in a tutorial’s hand-holding or a how-to’s steps without admitting it. Naming which one you’re writing is half the work.

On top of that, a handful of questions I try to answer before writing a line:

Which of the four am I writing right now? If the honest answer is “more than one”, split it. A reader on a task and a reader learning from scratch want opposite things from the same page.

Who arrives here, and what do they already know? Reference for an expert and a tutorial for a newcomer are different documents. Writing for everyone writes for no one.

Does this fact have an authoritative source somewhere else? If it does, link it rather than copy it. This is just single-source-of-truth applied to prose. Every duplicated fact is a future inconsistency waiting for its moment.

Will this sentence still be true in six months? If it’s a version, a flag, or a schema, probably not, so offload it. If it’s a reason, it will likely age well, so invest in it.

Can someone understand this section without reading the rest? If it only makes sense in order, you’ve written a story, and both the impatient human and the retrieving model will lose the thread.

So What Are We Actually Writing?

We spent years optimising documentation for a reader who doesn’t exist: the patient human working front to back through a narrative. The reader who actually shows up is impatient, arrives mid-task, and is increasingly a model acting on someone’s behalf.

Which leaves me with questions I can’t quite close out. If the most frequent reader is now a model, is the best documentation even prose, or is it a codebase made legible, an interface that describes itself, reasoning you can run? And if the ideal document is the one you never had to write because the system already explains itself, what does that make all the ones we still do?

Maybe the point was never to write documentation people read. Maybe it was to build systems so legible they barely need it, leaving only the one thing no system can explain about itself: why it turned out this way and not one of the others it could have been. That decision, and the roads you didn’t take, is the document worth keeping. The rest was always going to rot.