The Code That Nobody Can Read
There is software running in production right now that nobody fully understands. Critical systems — banking infrastructure, hospital software, logistics platforms — maintained by developers who inherited the code from people who left the company, who inherited it from people who never documented it because they intended to get around to it eventually. The documentation debt in the software industry is enormous, and it compounds every time someone adds to an undocumented codebase while meaning to explain it later.
Documentation is consistently ranked by developers as important but consistently deprioritised in favour of features. The result is predictable: systems that work but that only one person understands, knowledge that disappears when that person leaves, and onboarding experiences that take months when they could take weeks. Documentation is the most underrated programming skill because its value is primarily visible in its absence.
What Documentation Actually Encompasses
Documentation is not a single thing. It ranges from inline comments explaining why a particular approach was taken (not what the code does, which should be apparent from the code itself) to README files explaining how to install and run a project, to architecture decision records capturing why major technical choices were made, to API documentation describing what a service offers and how to use it, to user-facing guides explaining how to use a product.
Each type serves a different audience with different questions. Inline comments serve future maintainers of the specific code. README files serve developers encountering the project for the first time. Architecture documents serve developers who need to understand the system holistically. API documentation serves developers building against the interface. Good documentation practice involves maintaining all of these, not just one.
The “Why” Is More Important Than the “What”
The most valuable documentation explains why decisions were made, not what the code does. Code is self-describing in terms of what it does — a reader can trace through the logic. What code cannot tell you is why this approach was chosen over alternatives, what constraints were present, what was tried and didn’t work, or what assumptions the code makes that might not be obvious later.
Architecture Decision Records (ADRs) — short documents capturing a significant technical decision, the context it was made in, and the trade-offs considered — are one of the most useful documentation practices for teams. They create an audit trail of why the system is the way it is, which is invaluable when the original decision-makers have left or forgotten the context.
Documentation as Communication
The mental model shift that makes documentation easier to write is: documentation is communication with future readers, not a tax on current development. When you write documentation, you’re having a conversation with a developer (often your future self) who has a specific question in a specific context and needs a specific answer. Writing to answer that question specifically — “how do I run this locally?”, “why does this function exist?”, “what are the failure modes of this service?” — produces better documentation than writing to satisfy a general obligation.
The Practical Minimum
For developers who want to improve their documentation practice without a large upfront investment: maintain a README for every project that answers the four questions every new contributor will have (what is this, how do I set it up, how do I run tests, how do I deploy). Write inline comments for code that is tricky or non-obvious, focusing on why rather than what. Document public APIs with enough detail that a user could use them without reading the implementation. And when you make a significant technical decision, write two paragraphs about why — immediately, before the context is gone.
The developers who are consistently valuable on long-running projects are rarely the ones who wrote the cleverest code. They’re the ones who made their work legible — who invested in documentation that compressed onboarding time, prevented repeated mistakes, and let the system grow without accumulating mystery. That’s the compounding return on what looks, in the moment, like overhead.
Watch: Related Video
Sources
- Nygard, M. (2011). Documenting Architecture Decisions. cognitect.com/blog.
- Martin, R. C. (2008). Clean Code. Prentice Hall.
- Diátaxis. (2023). A Systematic Framework to Technical Documentation. diataxis.fr.