Documentation Rots. Some Kinds Rot Faster Than Others.
The honest version of 'I'll update the docs,' and why trying harder was never the fix.
“I’ll update the docs” is one of the most reliable broken promises in software. The person means it when they say it. They won’t do it, or they’ll do it once and not again, and in six months the same sentence comes back around with the same good intentions attached.
Discipline takes the blame, and the familiar fixes follow: a documentation step in the definition of done, a check in review, a cleanup every quarter. They rarely hold, because nothing here was broken by carelessness.
Any project keeps two kinds of documentation, and they go stale at completely different speeds. One barely rots at all. The other drifts faster than any quarterly cleanup can chase, and asking a team to maintain both with equal diligence is asking them to outrun a property of the system.
Two kinds of surface
A structured surface lives somewhere a script can read it: a schema, a registry, a YAML field, the spreadsheet column whose values come from a fixed list, the line that reads version: 2.7.4 and gets checked against something real. What they have in common is that a machine can see them, and that turns out to be the whole difference.
These hold up because something downstream depends on them being right. Let a value go wrong and a test fails, or a build breaks, or a check that used to pass quietly refuses to. The cost of staleness is loud and immediate, so someone pays it the same afternoon.
The other kind lives in sentences. Call it a narrative surface: the body of a README, the “what we do” page on the website, the summary that paraphrases a quarter of work for the people who will never read the work itself, the status section nobody touches after week three. These drift on their own quiet schedule, because nothing downstream depends on the exact words. Nothing breaks when a paragraph stops being true. The cost is just as real and far less visible, so maintaining it always loses to the work that has a deadline.
Why this matters
You can sort the documents in your own project right now, and it takes two questions. Can a script read it? Does anything break if it’s wrong? Two yeses and the document will stay honest on its own, because something is already watching it. Two nos and it is probably drifting as you read this, with nothing watching at all.
Walk a directory with those two questions in hand and the structured surfaces light up first: the schemas, the config files, the data you can grep. The narrative surfaces are the documents standing right beside them, explaining what they mean. If you have ever spent a Tuesday morning rereading a “what we do” page and quietly editing five paragraphs that no longer matched the work, you have already met one. Nothing forced that morning. You happened to look.
Writing fewer sentences is not the lesson. The narrative layer does work the structured layer cannot: a schema lists which fields exist, but only prose can tell you why the schema is shaped the way it is, and what the design was trying to protect. The useful move is to know which of your documents hold and which ones drift, and to spend the maintenance where the risk actually sits.
The two practical moves
Two structural changes bring the rot rate down, and neither asks anyone to be more disciplined.
The first is to move whatever can be moved out of sentences and into structure, without losing meaning. A surprising amount of narrative is a table that hasn’t been drawn yet. Take a paragraph from a real design system:
Our color tokens come in three tiers. Primitive tokens are the raw values, like blue-500. Semantic tokens map an intent onto a primitive, so action-primary resolves to blue-500. Component tokens bind a semantic token to one component, like button-background to action-primary.
That paragraph drifts the instant any of those mappings changes, and nothing notices. The same facts as a table do not:
The table sits one short step from being a file a script can read, and the day it becomes one, a wrong row breaks something. When a passage is only paraphrasing facts that already live in a structured file, the move is smaller still: link to the file instead of restating it. The more a document carries irreducible argument and the less it carries facts that exist elsewhere, the slower it rots.
The second move is to put an alarm on the surfaces that have to stay in sentences. A project’s summary will always live in narrative; the only question is whether anything notices when the summary and the underlying record start to disagree. Most teams don’t, until someone reads the summary aloud in a meeting and a colleague’s face changes.
The alarm can be almost crude, as long as it fires without being asked. The simplest version is a last-reviewed date on the summary and a check that compares it against the last-modified date of the source it describes. The source changes, the review date doesn’t, the check goes red, and the divergence raises its own hand. A richer version sets the summary and its source side by side during routine work, so the gap shows up in front of whoever is already there. Neither one writes the words for you. They make the cost of not writing them impossible to keep ignoring.
Either move helps; together they help more, and both bring the rot rate down without asking anyone to try harder. The price is a little design, paid once.
What this looks like in practice
Watch it happen once, in detail. A design system has its token file, which is structured, and a page explaining how the team thinks about color, which is narrative. In a planning meeting someone decides the primary action should read warmer, and action-primary gets repointed from blue-500 to indigo-500. The token file changes that afternoon, because a build depends on it. The color page still describes the old logic, the cool blue and the reasoning behind it, and it goes on describing it for months, because nothing breaks when it doesn’t. A designer joining in the spring reads the page, takes the reasoning at face value, and makes three defensible decisions on top of an explanation that quietly stopped being true. The freshness check from a moment ago is the entire fix here: the source changed, the page’s review date didn’t, and the gap announced itself long before anyone trusted the page again.
The same shape turns up everywhere once you have the eye for it. A research database stays current because findings get filed into it, while the summary that paraphrases those findings for executives is accurate the day it’s written and drifting by the next morning. A service catalog’s list of offerings stays honest because the team works from it, while the positioning paragraph explaining how the offerings fit together loses a little truth with every change in shape. In each case the working record holds and the description of it slips, for the one reason that matters: only the record had something downstream depending on it.
The honest version of “we’ll update the docs”
When someone says “I’ll update the docs,” the useful next question is which kind of document they mean. If it’s structured, the update is cheap and it will hold. If it lives in sentences, the update is also cheap right now, and it will rot, and the same conversation will come back around in six months unless something structural changes.
So the honest version of the promise isn’t “I’ll keep the page updated.” It’s “I’ll move what can be moved into structure, link to the source for the facts that live elsewhere, and put a freshness check on the part that has to stay in sentences.” That promise can be kept. The other one just keeps returning as a complaint.