A developer wrote thorough documentation for their service.
Years later, the service had changed entirely, but the documentation remained.
The senior developer found a junior reading it earnestly. “What are you learning?” they asked.
“How the service works.”
“You are learning how it once worked. Is that the same thing?”
The junior closed the document and opened the code.
Sitting with the Koan
Documentation is an act of faith. When we write it, we believe that the words on the page will remain true long enough to be useful. And sometimes they do. But software is not stone. It moves, grows, and is quietly rewritten by people who meant to update the docs and did not quite get around to it.
The koan does not condemn the documentation. It was thorough. It was written with care. The problem is not that someone wrote it down; the problem is what happened in the years between the writing and the reading.
Notice what the senior developer does not say. They do not say the documentation is wrong, or that the junior was foolish to read it. They ask a single question: “Is that the same thing?” This is the whole teaching. The junior has to answer it themselves, and they do, without a word, by closing the document and opening the code.
There is a quiet lesson here about the difference between the map and the territory. A map is a record of where things were when someone last looked. The territory does not wait. Code running in production is always the territory. Every README, every wiki page, every architecture diagram is a map drawn at a particular moment by a particular person with a particular understanding. That understanding was incomplete even then. Time has made it more so.
This does not mean we should stop writing documentation. It means we should read it differently. With curiosity. With a certain skepticism. With the question running quietly in the background: when was this written, and what might have changed? The most dangerous documentation is not the obviously outdated kind, with its broken links and references to services that no longer exist. It is the documentation that is almost right, that matches the code in nine out of ten ways, and so earns a trust it no longer entirely deserves.
The junior’s final gesture is worth sitting with. They do not argue. They do not ask what has changed. They go directly to the source. The code is not always easy to read. It may not be beautiful. But it does not lie about what it currently does. In this sense, the codebase is always the most honest document in the room. It is the thing itself.
For any developer who has ever confidently followed a tutorial into a wall of deprecation errors, or spent an afternoon implementing an integration that the API abandoned two years ago, this koan will feel familiar. We have all learned from documentation that was teaching us the past. The question is how quickly we notice, and whether we are willing to set down what we think we know and look at what is actually there.