Keeping the written thing true

A wrong document is worse than none

This is the objection that killed heavy specification in the 1990s and it was correct. A document that describes a system that no longer exists does not merely fail to help; it misleads with authority. Someone reads it, believes it, and builds on a false premise.

So any argument for writing more must come with a mechanism for keeping it true. Otherwise you are recommending a liability.

There are exactly two mechanisms that work: put it where the code is, and make something check it.

Mechanism one: same repository, same commit

The specification lives in the repository, next to the code it describes, and changes in the same pull request. Not a wiki. Not a ticketing system. Not a shared drive with a folder called Specs.

The reason is behavioural rather than technical. Updating a file that is already open in your editor and already in your diff costs about fifteen seconds. Opening a separate tool, finding the page, editing it and saving is a separate act of will, performed at the end of a task, when you are tired and it is Friday. The second one does not happen, reliably, on every team, for ever.

A simple layout:

billing/
  fx.py
  fx_test.py
  README.md          # what this module is for, and its decisions
docs/adr/
  0009-rate-limiter-availability.md
  0014-store-converted-amounts.md

And a review norm: a change to behaviour that does not touch the nearby prose gets a question in review. Not a block, a question. “Does the README still describe this?” is usually answered in ten seconds and occasionally catches something significant.

Mechanism two: make it executable where you can

Prose rots because nothing objects when it becomes false. Anything checked by a machine cannot.

Doctests. The example in the documentation is run as a test.

def to_minor(amount: str, currency: str) -> int:
    """Convert a decimal string to minor units.

    >>> to_minor("12.50", "USD")
    1250
    >>> to_minor("12.500", "KWD")     # 3 decimal places
    12500
    >>> to_minor("1200", "JPY")       # no minor unit
    1200
    """

Those three lines are documentation, specification and test simultaneously, and the KWD and JPY cases encode two facts about the world that a reader would otherwise not know. If somebody breaks the currency-exponent handling, the documentation fails.

Acceptance criteria as test names, from earlier in this module. pytest --collect-only gives you the specification back, and it is verified on every commit.

Schemas and contracts. An OpenAPI document that generates the client, a protobuf file that generates both sides, a JSON Schema validated in a test. Anything generated from a specification cannot drift from it, because drift is a build failure.

Links from code to prose. A comment naming a decision record means the code and the record are found together, and a reader who checks the link notices when it is stale.

What rots, and should

Be realistic about the categories.

• Decisions do not rot. Why you chose fail-open in August 2026 is a fact about August 2026 and remains true for ever. This is why decision records are immutable and superseded rather than edited.
• Descriptions of current behaviour rot fast. Keep them short, keep them near the code, and prefer generating them where you can.
• Tutorials and getting-started guides rot fastest of all, because they contain commands, versions and paths. If you have one, run it in CI: a script that follows your own quickstart on a clean machine is worth more than any amount of careful writing.
• Diagrams rot silently and completely. A diagram in an image file, drawn once, is wrong within a year and nobody will ever know. Diagrams written as text (Mermaid, Graphviz, PlantUML, all free) at least appear in diffs, which gives them a chance.

The deletion rule

The last piece, and the one that keeps the whole thing honest: delete documentation you are not maintaining.

When you find a page describing a service decommissioned two years ago, do not leave it because it might be useful. Delete it. It is in git if anyone needs it, and its presence costs everyone who reads it looking for something true.

The test to apply to any document: if this were wrong, would anybody find out? If the answer is no, either wire up something that would find out, or accept that it is a note rather than a specification, and file it accordingly.