Doc rot: the maintenance gap the end-to-end argument leaves open

Documentation does not have to change to become stale because the product (or the world) can move around it.

Software research described this maintenance problem decades ago. Lehman showed that a static program can become less useful as the reality it reflects changes.¹ Parnas described software that had aged “even though nobody has touched it” and documentation that becomes “increasingly inaccurate” when updates are deferred.²

A page can keep passing every existing check while losing its fit with the product or with the conditions in which the product is used. Each check may still return the right verdict within its scope even though no process brings the relevant claim back to the person or check able to reassess it after change.

Two questions#

A docs pipeline combines automated checks, review tasks, and people. Each can answer some questions and not others. A Markdown linter can report whether a file follows its rules. A live contract test can report observed API behavior. Choosing the current integration path requires product and user evidence.

Two questions expose the difference:

1. Can this person or check answer the claim with current evidence?
2. What will make that person or check look again over time, and who is responsible for acting on the result?

The end-to-end argument explains the first question. Saltzer, Reed, and Clark show that complete implementation depends on knowledge held by the application at the endpoints, although a partial lower-level version may still improve performance.³ Applied to documentation, the person or check must be able to reach the evidence the claim requires. A live contract test can answer a narrow question about endpoint behavior. A recommendation about when to use that endpoint needs current product and user evidence.

The second question accounts for time: an engineer can verify behavior during launch and never be asked to revisit it after release, while a linter can run on every release and check only form. A maintained path connects the person or check able to answer with a reliable trigger or cadence and assigns responsibility for the result.

The grid#

Carry one machine-testable claim through all four cells: “GET /foo?mode=summary returns HTTP 200 in the supported release environment.”

The bottom row is useful when its scope is explicit. A recurring linter keeps reporting on form; it does not report the endpoint’s current response. A change trigger also cannot answer the claim. It becomes useful by routing the page to a test or reviewer that can. The trigger and the reviewer together create the maintained path.

The grid uses a contract claim because a machine can answer it. A recommendation is harder. Deciding which integration path readers should use requires current product and user evidence. The same maintenance question applies: what event or schedule returns that recommendation to someone who can reassess it?

The known failure and the quiet one#

The familiar failure comes from reading a bounded green result as a broader verdict. For code, a mismatch sometimes announces itself through a test, type check, or runtime failure already operating for another reason. Many documentation claims have no executable consequence. A link checker reports whether it could reach a link when it ran. A linter reports rule conformance. A schema validator reports structural validity. All can be green while a product claim is false. Each result says only what that tool measured.

The quieter failure is orphaned knowledge. Someone can answer the relevant question and does so once, but no maintained path returns the page for review. The page remains in CI while the decisive review disappears.

A green build can coexist with either failure. One assigns broad meaning to a narrow result. The other fails to ask the right person or check again.

Swanson calls maintenance in response to a changed environment adaptive maintenance.⁴ Orphaned knowledge is an adaptive-maintenance failure: the means to answer exists, but no standing process invokes it after change.

When docs become machine input#

Automated readers make stale guidance travel faster. When a retrieval system, coding agent, or support workflow uses an orphaned page as source material, the same claim can appear in repeated answers or edits. A coherent page can produce working but outdated guidance.

LLMs do not create the maintenance gap. They can increase its reach when a workflow selects a stale page and gives it authority. The source still needs an owner and a trigger.

What to do#

Start with the material claims on a page. For “GET /foo?mode=summary returns HTTP 200 in the supported release environment,” a contract test can supply current evidence. Run it when the handler or contract changes and on a schedule, and assign responsibility for maintaining the test and acting on its result.

Guidance needs a broader mapping. Give each page or feature a responsible maintainer and connect it to the product area it describes. A mapping to existing dependencies can miss a newly introduced alternative, so the trigger must also cover the product capability or release area. A scheduled review provides a backstop for changes that no existing dependency can anticipate. Changes to source, schema, release state, deprecation status, or team ownership can then create a review task.

This routing creates maintenance and triage work. Use claim-level automation for material assertions a machine can check; page- or feature-level ownership can carry the rest. Event-driven triggers should fire only for changes that can plausibly affect the guidance.

Run the two questions on each material page or claim: a missing answer to the first reveals a knowledge gap, and a missing answer to the second reveals an ownership gap. The end-to-end argument shows where an answer can be found, and maintenance supplies the return path that lets the system ask again after change.

Notes#