Documentation is the thing most engineering teams say they value and most engineering teams treat as optional. It sits at the bottom of every sprint, gets sacrificed when timelines tighten, and is written — when it is written — in the last hour before a launch, by whoever is left.
The result is what you would expect. Docs that describe an older version of the system. Docs that assume knowledge only the original author had. Docs that answer questions nobody is asking and ignore the ones people actually have. In aggregate, docs that are worse than nothing, because they inspire a false confidence and then betray it.
The teams that break out of this pattern do so by making a specific philosophical shift. They stop treating docs as a byproduct of the work and start treating them as one of the primary artifacts the work produces. This is a small change in framing and a large change in outcome.
Docs are a design tool
The most underrated use of documentation is not communicating with other people. It is thinking. Writing the doc forces you to name the concepts you have been carrying around in your head, and naming them tends to reveal that some of them are confused, redundant, or wrong.
Teams that write design docs before they write code discover architectural problems while those problems are still cheap. Teams that skip the doc discover the same problems in the code review, or in the incident, or in the migration. The problems are the same. The cost of finding them is not.
This is why the most productive senior engineers we know write more documentation than their juniors, not less. They are not writing it because they need to communicate. They are writing it because writing is how they think, and thinking on paper is faster than thinking in code.
Docs are a product surface
For infrastructure tools, docs are the product. The API is not what people use; the docs about the API are what people use. A beautifully designed API with bad docs is, for most users, indistinguishable from a badly designed API. The docs are the interface between the tool and the user's mind, and if that interface is broken, nothing else about the tool matters.
This has a specific practical implication: the person writing the docs should be as senior as the person writing the code. Delegating docs to whoever has the least to do is delegating the user experience to whoever has the least context. It is the same category of mistake as letting a junior engineer make your database schema decisions.
Docs are a maintenance artifact
The docs you write on day one are for the person shipping the feature. The docs you maintain over time are for the person debugging the feature at 3 AM eighteen months later. That person is often you, and you will not remember what you were thinking.
Runbooks, in particular, repay their cost faster than almost any other engineering artifact. A five-minute runbook, written the first time you resolve an incident, will save hours the next time the incident recurs — and it will recur, because incidents that happened once tend to happen again.
The teams that write runbooks routinely have quieter on-call rotations. This is not because they have fewer incidents. It is because their incidents cost less. The math is embarrassingly simple, and most teams still do not do it.
The cost objection
The standard objection to serious documentation is that it takes time away from shipping. This is empirically false for any timeframe longer than a quarter. Teams with good docs onboard faster, debug faster, migrate faster, and change architecture faster. The doc time pays for itself, usually many times over, within the first year.
The objection persists because the cost of writing docs is visible and immediate, while the benefit is invisible and delayed. This is a classic present-bias failure. Recognizing it as such is most of the work.
What we try to do
At Fewzon, we treat docs as code. They live in the same repo, they get reviewed in the same PRs, they get updated in the same commit that changes the behavior they describe. A PR that changes behavior without updating the docs is not done. This is not a policy we announce; it is a norm we enforce, quietly, in review.
The result is not more documentation than other teams produce. It is documentation that is trustworthy, which is a rarer and more valuable thing.