Picture a factory where every machine is perfectly calibrated and every operator is an expert, and yet, every time someone new joins, it takes them three weeks to figure out what each lever does. Nobody would call that factory efficient. And yet that’s exactly how a huge number of software and hardware projects run: the product is excellent, the team is brilliant, and the knowledge lives only inside the heads of the people who built it.
Documentation isn’t a cosmetic add-on to development. It’s a production phase, just as real as testing or quality control, except that, unlike those phases, it doesn’t fail loudly. A bug breaks the application in public. The absence of documentation breaks things in private: in the new hire who takes twice as long to become productive, in the customer who abandons a product because they never understood how to use it, in the engineer who inherits a system and has to do code archaeology just to understand a decision made two years ago that nobody remembers anymore.
The Cost Nobody Sees Being Paid
Here’s the central psychological trap: whoever decides not to document experiences the savings immediately (a faster sprint, an earlier release), while someone else pays the cost, later. It’s almost a problem of social physics: the benefits of documenting are spread out across the future and across other people, while the costs are concentrated in the present and in yourself. Any leader who only looks at the short term will systematically underestimate how much it’s worth to write things down.
And the real cost isn’t small. Industry practice and research both point to something intuitive: bringing a new person onto a team without proper documentation can take weeks instead of days. Technical support without clear documentation generates repeated tickets that eat up hours of senior engineers’ time answering questions a good article could have solved in seconds. And in hardware, the lack of clear specs explaining why a design decision was made can lead to someone, two product generations later, repeating a mistake that was already solved, simply because nobody wrote down why that path had been avoided.
What Documentation Actually Preserves
Code, or a circuit schematic, tells you what exists. It rarely tells you why it exists that way and not some other way. The alternatives that got discarded, the constraints that forced an imperfect decision, the business context that no longer applies but explains a technical oddity: none of that gets recorded in the final artifact. It’s lost forever, unless someone wrote it down.
That’s what turns documentation into something closer to institutional memory than a simple manual. When a key person leaves (and at some point, they always do), what’s really lost isn’t their code, which is still sitting right there. What’s lost is the why. And that why is exactly what documentation can save.
When Documenting Is a Waste
But let’s be honest: not all documentation is worth the same, and treating it as an absolute commandment is just as naive as ignoring it. Documenting a throwaway prototype, or a system that’s about to change completely next week, is like painting the facade of a house that’s about to be demolished. The value of documentation is proportional to the expected lifespan of what it documents, and to the distance (in time, in context, in identity) between whoever writes it and whoever eventually reads it.
Outdated documentation, on top of that, isn’t neutral: it’s dangerous. It lies with the authority of the written word. A reader trusts it, acts on it, and discovers the mistake too late. Documenting poorly, or letting documentation rot without upkeep, can be worse than not documenting at all.
How to Decide, Even If You’ve Never Thought About It
If you’re leading a software or hardware initiative and want to know how much to invest in documentation, ask yourself three questions, in this order:
Who’s going to read this, and will they be able to ask me directly? If the answer is “anyone, at any time, with no chance to ask” (an external developer using your API, an everyday user of your product, your own team three years from now), the value of documenting climbs sharply.
Is this going to last, or is it disposable? Don’t document what you’re about to throw away. Document what will outlive the person who built it.
Am I documenting the what or the why? The code already explains the what; duplicating it in comments is wasted work. What’s irreplaceable is the why: the decisions, the discarded paths, the trade-offs. If you don’t write that down, nobody will.
Documentation isn’t the brake on an agile project. It’s its life insurance: invisible while everything’s going fine, and decisive on the day something, or someone, stops being available.