.png)
22 hours ago
1
Of the four tenets of the Agile Manifesto, one gets the least attention:
"Working software over comprehensive documentation."
I used to wonder if this line was still necessary. Waterfall is dead, right? We don’t write 40-page specs anymore. We iterate. We deploy constantly. Who even reads documentation? But then along came ADRs — and suddenly, waterfall was back.
While documentation isn't forbidden by the Agile Manifesto, it should always take a backseat to the most important document: the source code. You’ll hear people claim that ADRs, RFCs, and other formats are a modern, Agile-friendly kind of documentation — sleeker, lighter, more collaborative than the bloated specs of the '80s and '90s. But in practice, they break the single most important rule of useful documentation:
Documentation should describe the current state of software, not future aspirations.
It’s that simple.
Documentation that reflects intention, aspiration, or “alignment” might feel useful — but it turns stale the moment real feedback hits. Plans change. Code evolves. No plan survives contact with the enemy.
That’s why documentation should follow implementation: to stay grounded in reality, not stuck in a pitch deck. When written too early, docs have a way of becoming gates — demanding buy-in, slowing progress, inviting bureaucracy.
Agile isn’t about asking permission. It’s about moving fast, learning as you go, and letting the code lead.
There’s a new class of documentation making the rounds in modern software teams. It looks clean. It lives in Git. It uses Markdown and has PRs and approvals. It feels agile-ish — but functionally, it’s just hipster waterfall.
Some common offenders:
ADRs – Architectural Decision Records are documents used to capture important technical decisions about a system — typically outlining the context, options considered, the chosen approach, and reasoning behind it.
RFCs – Requests for Comments are documents shared within an organization to propose a change, invite discussion, and gather feedback from stakeholders before implementation begins.
Alignment Docs – Alignment documents are often used when multiple teams are collaborating and want to clarify shared goals, responsibilities, timelines, or interfaces to avoid conflicts and miscommunication.
These docs are clean. Structured. Reviewed. And deeply fictional.
Agile is iterative. You try, you check, you try again. But these types of documents — especially when written beforehand — don’t reflect that reality. They freeze assumptions before they’ve been tested and codifies them as barriers to change.
Worst of all, these documents quickly morph from collaborative artifacts to bureaucratic hurdles. Once written, they attract approvers. Suddenly, progress hinges on buy-in. What starts as a discussion becomes a checkpoint — a justification — a gate. And who benefits from that? Usually not the engineers. These docs tend to serve management’s need for perceived control more than a developer’s need for real clarity.
When painting, you draw a few lines. Step back. Add a little color. Erase something that felt wrong. You start to get a sense of what the painting wants to become. That’s the process.
Writing an ADR is like composing a detailed essay about your sketch — before you’ve decided whether to keep it, paint over it, or throw the whole canvas out. Even worse, once the essay exists, you’re obligated to justify why your final painting doesn’t match the thing you wrote when the canvas was still blank.
That’s why ADRs and RFCs so often become problematic. They:
preserve assumptions that no longer make sense.
make it harder to change direction without "justifying the deviation."
create process drag instead of technical alignment.
encourage teams to commit too early to ideas that haven’t been pressure-tested.
In fact, if your ADRs aren’t out of date, that’s a red flag.
If your ADR is accurate after three sprints, you’re ignoring what the code is trying to tell you.
Good teams learn. They adapt. They refactor. And when they do, the documentation rots. If it doesn’t, you’re not learning. You’re not Agile.
Documentation that works doesn’t try to predict the system. It describes it. Faithfully. Honestly. And in sync with reality.
That means no aspirational roadmaps disguised as design docs. No idealized blueprints frozen in time. Just living documents that reflect what the code actually does — as it changes.
Here’s what tends to work:
Generated docs — These are the gold standard for staying accurate. Because they’re built directly from the codebase, they evolve when the code evolves. API documentation, database schemas, typed interfaces, route maps — if you can generate it, you should. These docs can’t drift because they’re pulled from the source of truth.
Inline code comments — When kept up to date, these are small but powerful acts of code annotation. They sit where the context lives, next to the logic they describe. They’re small, conversational, and close enough to get deleted or updated the moment they lie.
Project READMEs — A well-written README anchors a project. It describes what the code does right now, how to run it, and how to contribute. When maintained alongside the codebase, it becomes the most accessible, low-friction entry point to understanding a system. It's not aspirational — it's operational.
Literate programming — This is where narrative and implementation meet. Code and commentary live together, woven into the same artifact. When you explain what your code does in the same place that it does it, you force clarity of thought and invite better structure. Literate programming doesn’t tell stories about what might exist; it tells the story of what exists now.
All four approaches work because they are anchored to the code itself. They resist drift. They avoid fiction. And most importantly:
They document the system that exists — not the one someone hoped would exist when they wrote a Google Doc three weeks ago.
Is it any wonder the authors of the Agile Manifesto valued working software over comprehensive documentation? They’ve seen what happens when teams make documentation the source of truth: endless effort poured into updating, reviewing, versioning, syncing — and still, it lags behind reality. They've seen documents become bottlenecks waiting for approvals.
You either prioritize working software or comprehensive documentation. The Agile Manifesto chooses working software. Or as Facebook’s old hacker culture doc put it:
“Code wins arguments”
You can spend your day updating documentation and chasing signatures — or you can make real progress in your code. Which would you prefer?
