What is Documentation Rot?

Why It Matters

Documentation is the only artefact in a codebase that is wrong the moment it is finished. A function keeps working until someone changes it; a description of that function stops being true as soon as the pull request lands. The gap is not caused by neglect. It is caused by describing a moving thing in a form that does not move with it.

The cost lands in the places that are hardest to measure: the new engineer who follows a setup guide that no longer works, the on-call responder who trusts a runbook for a service that was renamed, the reviewer who reads a design document as current when it describes last year’s architecture. None of these show up as a bug, and all of them cost hours.

What Causes It

The source moves. Every merge is an opportunity for the prose to become false, and merges happen far more often than documentation reviews.

The doc is a snapshot. A page written at a point in time has no mechanism to notice that time has passed. It is accurate until proven otherwise, which means it is trusted until it misleads someone.

Nobody owns it. Documentation is usually everyone’s responsibility, which in practice means it belongs to whoever last needed it. Unowned prose is not maintained, it is abandoned in place.

It is not on the critical path. A stale README does not fail a build. Work that cannot break the pipeline is deprioritised against work that can, which is rational per sprint and expensive per year.

Generated docs that are never regenerated. A generator run once produces the same rot as a page written by hand, with the added problem that it looks authoritative because a tool made it.

Where It Breaks

The onboarding path is the first casualty. Setup instructions are the most-read and fastest-decaying documentation in most repositories, because they depend on the whole environment rather than one file.

Diagrams decay fastest of all. A diagram asserts relationships, and relationships are exactly what refactoring changes. An out-of-date architecture diagram is worse than none, because it is confidently wrong about the shape of the system.

Runbooks fail under pressure. A runbook is consulted during an incident, which is the worst possible time to discover it describes a service that no longer exists.

Intent documented as behaviour. A design note says what the author meant to build. If it is read as a description of what runs today, every subsequent deviation looks like a bug.

Volume read as coverage. A repository with thousands of pages of stale docs feels documented. The measure that matters is how much of it a reader can act on today.

How Flytebit Handles It

We treat documentation as a build artefact rather than a writing task: generated from the repository on every commit, so the description and the code cannot diverge for long. The output is regenerated rather than edited, which means the fix for staleness is a pipeline that runs rather than a person who remembers. The problem is described in The Developer Documentation Dilemma, and the product that does the work is DOCKR.