Crypts and Commits: This Documentation Isn't for You

The Audience I Didn't Know I Had — Part Two

When I leave a software project, I want the next person to be able to take it over without needing me in the room.

Sometimes that next person is another engineer. Sometimes it is someone joining the team, a client receiving a handoff, or a developer inheriting a repository they did not choose. Sometimes it is me, six months later, staring at a decision I apparently made for a very good reason and having absolutely no memory of what that reason was.

That is the documentation habit I have been building for most of my career. It is not just “write a README.” It is trying to leave an explicit path into a project: how to start it, how it is shaped, what decisions were made, what someone should be wary of, and enough of the current understanding that the next person can safely take the next action.

The habit became systematic for me in 2012, at an EHR startup that was growing quickly. We went from four developers to forty in only a few years. For a SaaS company, that kind of growth does not happen by accident, and it was not only a headcount problem. The product was growing too: more applications, more repositories, more experiments, and more ways for context to get stranded with the person who happened to create it.

We had a small development team and thin onboarding documentation when I started, so I began writing it as part of my own onboarding. Then I started doing the same thing for every project I created. Markdown files and repository-hosting tools made it easy to put the material where it belonged: next to the source code, not somewhere a person had to remember to find.

The pattern was simple at first. A README.md explained how to stand up a development environment, or pointed to an ONBOARDING.md that did. On a larger application, that expanded to architecture notes, runbooks, release notes, and the other artifacts needed to understand the project as a living thing.

When someone new joined a project, one of their first jobs was often to update the documentation. That was not busywork. A new set of eyes was a good way to find out which parts of the handoff had aged badly.

At my current job, people have a name for the result: “John-ifying a repo.” It is half joke and half compliment. You can often tell which repositories I have touched because there is a clearer path into the project than there was before.

I did not start caring about that in 2012. The startup experience simply forced an older professional instinct into a repeatable practice.

Read the documentation. Then be suspicious of it.

RTFM is an old joke because it contains a real complaint: the answer is often in the documentation, and someone still has to go read it.

But I think the joke is usually too simple. The actual tension is not between people who write documentation and people who refuse to read it. The tension is that both of these things are important:

• You need to read the documentation, because code alone does not preserve all the intent, operating knowledge, and tradeoffs behind a project.
• You need to avoid trusting the documentation too much, because it can be stale, incomplete, aspirational, or simply wrong.

I have been on plenty of support calls after a handoff where the practical solution was to get on a call and pull up the documentation together. I have also inherited projects and asked questions that were probably answered in a file somewhere. I do not blame other engineers for that. A human being with limited time has a good reason to be skeptical of a long document, especially when there is no guarantee it describes the system they are actually looking at.

That skepticism is healthy.

The problem is not that documentation fails to become a perfect source of truth. The problem is when we treat it as one. Planned architecture is easy to write. Aspirational architecture is even easier. The difficult thing is updating the record after the work teaches you what the system really is.

This is why I cared about making a new engineer update the onboarding material. It was a built-in reminder that the handoff had to meet reality. Documentation does not replace judgment. It is supposed to give judgment a better starting point.

A new kind of reader

AI coding assistants changed the value of this habit for me, but they did not change its underlying purpose.

The first connection is the one that feels almost obvious once you see it. I have always written for a forgetful future self. If I return to an old project after enough time away, I do not remember the history of every architectural decision. I need to read enough context to restore the reasoning before I change the code.

An LLM is even more literally that kind of collaborator. It does not retain project understanding between turns or sessions unless that context is supplied again. If I gave a human coding partner a task every morning and they had forgotten everything from the day before, we would be very nearly in a Monty Python sketch. With an AI coding assistant, that is simply the starting condition.

The second difference is patience.

Ask a human engineer to 10 paragraphs of context and they may reasonably ask what they actually need to know. Ask them to read 100 paragraphs and the question becomes even more reasonable. An LLM can receive either amount of context and produce an answer without becoming frustrated, bored, or resentful of the reading assignment.

That does not mean context is free. There are still limits, costs, and real questions about whether a large collection of material is useful. It does mean that a practical constraint has changed. An agent can consume a volume of documentation that a human developer would understandably skim, defer, or reject.

I saw a small version of this with an internal command-line tool that calls a data pipeline. The tool was not even especially clean: it inconsistently used “modified” and “updated” in its options. An agent would use the wrong term, get a parsing error, ask for the generated help with -h, and update the command. It would repeat that pattern without asking me for help.

The point was not that the agent was somehow better than a human engineer. It was that the agent kept consulting the available context. A human might have asked me about the same command three or four times, even with the help text sitting there. The agent encountered an error, read what the tool had to say, and kept moving.

I had not consciously thought of generated command help as documentation before that. But it is. Good error messages, consistent task runners, discoverable command options — they are all part of the conversation between a system and someone trying to use it.

The fuller conversation between an engineer and an AI assistant is code and documentation together.

More context makes the old risk more important

The agent’s patience is useful only if the context it reads is worth reading.

This is where I think it would be easy to get the story wrong. The lesson is not “give the model more tokens.” An agent will patiently consume an enormous architecture document. It can also patiently consume an enormous architecture document that describes a system which no longer exists.

In some ways, the agent makes the old documentation problem easier to hide. A skeptical human might stop and ask why they are being sent this much material. An agent will simply work with what it has been given. If the information is aspirational, stale, or missing the actual reason behind a decision, it can create a very polished result built on a bad premise.

So the responsibility does not go away when the reader changes. It increases.

My job is not to produce mountains of text for an AI to obey. It is to curate the what and why behind the work, then make sure that record changes when implementation teaches us something new. The AI does not eliminate the RTFM tension. It changes who is willing to do the reading, while raising the stakes of getting the record wrong.

An experiment, not a review assignment

That was the context for a recent architectural handoff.

I used Claude Code to plan a change and work through the details, resulting in a fairly extensive plan of attack. A teammate was going to implement the work with Windsurf. The plan moved from my agent and my machine to his agent and his machine.

During the handoff, he pushed back on the length of the documentation. Why had I given him the full document when a summary would do? Did I really expect him to read all of it?

He was not wrong to ask.

I explained that I did not expect him to treat the document as a human review assignment. It was the full context of what I thought needed to happen and why, curated with my coding assistant. I asked him to give it to his AI at the start of the change, then tell me where the reasoning turned out to be wrong once it met the codebase.

I was not handing him a potentially condescending architecture document. I was handing him an experiment to run.

The result was not that the plan turned out to be perfect. It was more useful than that. His implementation produced concrete feedback about where the original analysis held up and where it did not. We updated the architecture documentation to match the post-change reality.

The plan had traveled across people and across tools. The documentation gave the second agent enough context to begin. The implementation tested that context. The revised documentation recorded what we learned.

That is the entire practice in miniature: read the documentation, distrust it enough to test it, and revise it against reality.

His original pushback remains valid. The document was too long for the human task at hand. The agent’s patience made the experiment feasible. The human engineer’s judgment made it useful.

What I document now

I now preserve more of the planning context created with an AI coding assistant, not just the finished state of the code. A documentation-consistency review is part of a planned change. Sometimes the AI closes the gap; sometimes I do.

That produces more documentation than I ever expected to create. It also has a different primary reader. The material still lives in the same repository as the code. A human is not excluded from it; another engineer can have their own AI read the relevant context as they plan work. But some of these documents are no longer primarily written for a person to sit down and consume from start to finish.

They are written for an agent working with that person.

That is what I now tell people when I introduce the practice. Imagine how much documentation you would need if your coding partner forgot the entire project every night. For a human partner, it would be absurd. For an LLM, it is the actual operating environment.

I used to document so that a future person could take over without me. Now one of those future collaborators is an AI that forgets everything between conversations and never complains about the reading assignment.

That makes the old habit more useful. It also makes the old warning more important: read the documentation, and then make sure reality agrees with it.

The next question was how to make that handoff discipline less dependent on one person’s personal habits. That is where Crypts and Commits begins.