I rarely write documentation because someone asks me to. More often, it starts after I’ve answered the same question a few times. The first conversation usually feels ordinary. The second is a small coincidence. By the third, it becomes difficult to believe I’m explaining the same thing over and over simply because people aren’t paying attention. Usually they’re paying attention.
They’re just arriving from somewhere else. So I write the page. Not because I think it’s finished, but because, at that moment, it’s the clearest explanation I have. It almost never stays that way. A few weeks later I’ll notice a sentence that no longer feels right. A meeting reveals another assumption that had never been written down. Someone asks a question I hadn’t thought to answer. Without really deciding to, I rewrite another paragraph.
The document changes for the same reason the system changes. Because my understanding changes. For a long time, I assumed that was a weakness. Surely good documentation should stay stable. If I kept editing the same page, perhaps I simply hadn’t written it well enough the first time. That explanation sounded reasonable until I looked back through older versions.
Most of the edits weren’t corrections. They were better questions. The feature hadn’t changed very much. The way I understood it had. Looking back, that feels obvious. No complex system reveals itself all at once. Understanding accumulates gradually. A production issue explains an old design decision. A customer question exposes an assumption nobody had noticed before. A conversation with a developer suddenly makes a business rule much easier to describe.
The document quietly follows those discoveries. I don’t think documentation is valuable because it captures everything. It can’t. By the time you’ve finished writing, the system has already continued moving. What it can capture is something much smaller. How one person understood the system at a particular moment, after spending enough time with it to stop asking some questions and start asking better ones.
That turns out to be surprisingly useful. Not because future readers inherit the answers. Because they inherit somewhere better to begin. The people who open those pages are rarely the people who wrote them. They’re usually joining a project halfway through. They weren’t in the workshop where a decision was made, or the production incident that quietly changed everyone’s thinking. They don’t have years of conversations to draw on.
A document can’t recreate those experiences. Sometimes it can shorten the distance. I still go back and rewrite old pages. Not because they’re wrong. Because I am. Or, at least, because I understand the system a little differently than I did six months ago. That’s probably why I no longer think of documentation as a record of what a system is. It’s a record of what someone understood—until they understood a little more.
And somewhere in the future, someone I haven’t met yet will probably start from there, instead of where I did.