There’s a belief quietly spreading across Agile teams: that because we move fast and iterate often, we don’t really need to write things down. I think that’s a mistake — and the data backs it up.
“Working software over comprehensive documentation” is a trade-off, not a ban. The Manifesto itself says there is still value in documentation.
We’ve misread a single line from the Agile Manifesto and turned it into a licence to forget. The consequence? Tribal knowledge locked in the heads of developers who eventually leave. Mystery codebases. Costly onboarding. Decisions impossible to reconstruct a year later.
Research confirms this isn’t just a gut feeling. A study of 79 agile practitioners across 13 countries found that over half considered documentation important or very important — yet reported too little of it existed in their projects. Direct communication alone, as the Scrum literature advocates, simply isn’t enough [1].
More strikingly, a 2024 study of 600 software engineers in the UK and US found that projects with documented requirements before development began were 50% more likely to succeed [2]. Ignoring documentation doesn’t make us faster — it sets up the team for future slowdowns and failure.
The answer isn’t to go back to writing 200-page requirement specs. It’s to document the right things: the “why” behind technical decisions, runbooks for incidents, and onboarding context that helps new engineers contribute quickly. A good Architecture Decision Record (ADR) is three paragraphs. A solid README takes an afternoon. These are small investments with compound returns.
We track technical debt. We schedule refactoring sprints. Documentation debt deserves the same respect — because it costs just as much when it comes due, usually at the worst possible moment.
Write it down. Not everything. Just enough that the next engineer has a fighting chance.
References
[1] Stettina, C.J. & Heijstek, W. (2011). Necessary and Neglected? An Empirical Study of Internal Documentation in Agile Software Development Teams. Proceedings of SIGDOC 2011, Pisa, Italy. https://dl.acm.org/doi/10.1145/2038476.2038509
[2] Ali, J. & J.L. Partners (2024). 268% Higher Failure Rates for Agile Software Projects. Engprax Research. https://www.engprax.com/post/268-higher-failure-rates-for-agile-software-projects-study-finds/
[3] Beck, K. et al. (2001). Manifesto for Agile Software Development. https://agilemanifesto.org