It was late enough that the office lights had changed from bright to tired. We were preparing a small release, and someone asked why one payment setting had to stay disabled in production. The answer was not in the code. It was not in the ticket. It was in a short document written six months earlier by a teammate who probably did not know how grateful we would be at that moment.
That is one reason I love writing documentation. Not because documentation is always pleasant, or because every page stays fresh forever. I love it because good documentation is a quiet form of care for future work. It gives tomorrow’s team a starting point. It reduces the number of times people have to interrupt each other to recover context. It lets a codebase carry some of its own memory.
In software, we often celebrate the visible parts: the feature shipped, the architecture diagram, the clever refactor, the clean pull request. Documentation is less visible. It rarely gets applause in a sprint review. But the absence of it is felt everywhere. A new teammate takes twice as long to understand a service. A production issue waits while people search Slack history. A decision is reopened because no one remembers the trade-off. A workaround becomes permanent because the original reason disappeared.
Documentation does not need to be a huge manual. Some of the most useful docs I have read were small: a README that explained how to run the project, an ADR that recorded why the team chose one queue over another, a troubleshooting note for a flaky integration, a short example request and response, a migration checklist, a page that said “do not remove this flag until these three customers have moved.” Clear beats grand.
Writing docs also improves thinking. When I try to explain a design in plain language, vague parts become obvious. If I cannot describe the boundary of a module, maybe I do not understand it yet. If I cannot explain when to use a tool and when not to use it, maybe the rule is not mature. Documentation is not only an output after the work. It can be a way to discover whether the work is coherent.
The best documentation respects the reader’s situation. A person reading docs is often trying to do something under time pressure. They do not need a performance of expertise. They need a path. What is this thing? When should I use it? How do I run it locally? What can go wrong? Where are the logs? Who owns it? What decision should I not casually reverse? A document that answers those questions is already valuable.
There is a danger in treating documentation as a separate project that happens after all “real work” is done. That version usually fails. People are tired, context has already started to fade, and the doc becomes either too broad or too outdated. The healthier habit is smaller and closer to the work: update the README when setup changes, add an example when an API behavior is confusing, record a decision while the trade-off is still fresh, leave a note after an incident before the memory dissolves.
Documentation also has a social side. It lowers the cost of asking beginner questions because some answers are already written. It helps remote and async teams because context does not live only in meetings. It makes ownership less fragile because one person’s memory is not the single point of failure. It gives quieter teammates another way to contribute: not by speaking the most, but by making the path clearer for everyone after them.
Of course, documentation can become stale. It can be too long, too abstract, or too disconnected from the code. That is not a reason to avoid it. It is a reason to keep docs close to the places where people use them, to delete pages that no longer help, and to treat examples as living tests of understanding. A small accurate note is better than a polished document no one trusts.
When I write documentation, I often imagine a tired person in the future, maybe myself, trying to understand why something works this way. I do not need to impress that person. I need to save them a little confusion. If a document can turn one late-night mystery into a five-minute check, that is enough reason for me to keep writing.