Ever notice how ideas in software development tend to come full circle? There was a time when we put a lot of effort into documenting everything up front. It wasn’t perfect, but many of us believed that gaining clarity early would lead to better decisions later on.
Then the world sped up. Markets moved faster, customers expected continuous improvement, and the industry responded. Agile methodologies emerged as a way to shorten feedback loops and stay closely aligned with real user needs. “Working software over comprehensive documentation” became a guiding mantra, and it made sense. It kept teams focused on delivering value rather than writing paperwork for its own sake.
But in practice, some teams took that mantra a bit too literally, almost as if “documentation doesn’t matter as long as we ship.” The Agile Manifesto never said documentation has no value. It simply warned against letting documents slow us down. Skipping documentation entirely might reduce overhead in the moment, yet it often creates a different kind of waste: confusion, rework, and lost context. A lack of shared understanding doesn’t remove cost; it only postpones it.
Today there’s a quiet return to writing things down for clarity. Techniques like Architecture Decision Records, specification by example, and lightweight design docs are gaining traction again. Not as bureaucracy or thick binders on a shelf, but as living tools that help teams move quickly without losing meaning. Documentation is returning not to slow us down, but to make sure our speed is sustainable.
This shift even aligns with the tools we’re beginning to rely on. Code generation, model-driven systems, and AI-assisted development all depend on precision. You cannot feed a vague idea into a generation engine and expect reliable software to emerge. A clear specification, however, can be turned into code. The more we ask machines to help us build, the more disciplined our thinking needs to become. That kind of discipline starts to look a lot like the documentation we thought we could neglect.
Maybe that’s the lesson behind these cycles. Writing down what we mean isn’t a step backward. It’s part of moving forward. Speed still matters, but clarity is what makes speed repeatable and trustworthy. If both humans and machines can clearly understand what we intend to build, then we can move fast with purpose.
In that sense, the renewed interest in documentation isn’t about going back to the past. It’s an investment in sustainable velocity, the kind of speed we can maintain with confidence over time.
Claus Jepsen 