Article illustration 1

"Documentation should describe the current state of software, not future aspirations."

This provocative thesis from software engineer Adam Ard strikes at the heart of modern development practices. In his Rethinking Software essay, Ard contends that Architectural Decision Records (ADRs), Requests for Comments (RFCs), and alignment documents—despite their GitHub-hosted Markdown sheen—represent a dangerous regression to pre-Agile waterfall methodologies.

The 'Hipster Waterfall' Problem

While Agile's "working software over comprehensive documentation" tenet aimed to bury bloated specifications, Ard observes these new document formats have resurrected the same flaws:

  • Premature Fossilization: ADRs/RFCs capture untested assumptions before code validates them
  • Bureaucratic Gates: Approval processes prioritize stakeholder alignment over rapid iteration
  • Reality Drift: Documents become fictional narratives as code evolves during implementation

"Once written, they attract approvers," Ard warns. "What starts as discussion becomes a checkpoint—a justification—a gate." He likens the practice to writing an essay about a painting before the first brushstroke: the resulting artwork inevitably diverges from the initial vision, forcing wasteful justification of "deviations."

Documentation That Actually Works

Ard advocates for documentation anchored to operational reality:

1. **Generated Documentation** (OpenAPI, DB schemas)
   - Auto-synced with code; zero drift risk

2. **Inline Comments**
   - Contextual, deletable when obsolete

3. Project **READMEs**
   - Current-state operational guides

4. **Literate Programming**
   - Code and narrative woven together

These formats share a critical trait: they document what exists, not what someone hoped would exist during planning. Generated documentation particularly earns Ard's praise as the "gold standard" since it derives directly from the codebase.

The Agile Imperative

The core conflict? Teams can't prioritize both comprehensive pre-coding documentation and rapid iteration. Ard cites Facebook's hacker mantra—"Code wins arguments"—as the antithesis to documentation-driven development. When documentation becomes the source of truth, teams inevitably sacrifice agility for the illusion of control.

As Ard starkly concludes: "If your ADR is accurate after three sprints, you're ignoring what the code is trying to tell you." True agility requires documentation that follows implementation—not the reverse.

Source: Adam Ard, Rethinking Software