The Documentation Debt Nobody Gets Paged For
Why documentation debt compounds invisibly, what it costs by the time anyone notices, and how to turn staleness into a signal your team actually sees.
A failing test turns the build red. A type error stops the compiler. A dependency with a known CVE opens a pull request by itself at three in the morning, unprompted, and tags whoever touched it last. Every artefact in a modern repository has something watching it, and something that shouts when it breaks. Every artefact except the one your customers actually read.
Documentation is the only thing in your repository with no failure signal at all.
Everything else in the stack has an alarm
Line up what happens when each part of a codebase stops being correct:
| Artefact | How it fails | Noticed within |
|---|---|---|
| Test suite | red build | seconds |
| Type signatures | compile error | seconds |
| Dependencies | CVE alert, bot PR | hours |
| Uptime | pager | minutes |
| Error rate | alert threshold | minutes |
| Help article | nothing happens | months, by a customer |
That last row is the entire problem. An article that stopped being true in March behaves exactly like one that is still correct. It renders. It ranks. It gets found. Nothing about it looks wrong until somebody follows it, fails, and decides what to do about that.
Some of them write in. Most just leave.
Why "we'll update it later" always wins
Documentation work loses to feature work for a structural reason rather than a cultural one, and it is worth being precise about which.
Feature work arrives with a date and a person asking about it. Doc work arrives with neither. Nobody is waiting on the article, no sprint closes because of it, and the only person who will ever notice its absence is a customer you have not met yet who will not tell you why they left. Put those two on a board together and the outcome is not in question - it never was, and it will not be next quarter either.
So the debt accrues. Quietly, at a rate nobody measures, in a place nobody checks.
The compounding is the nasty part. Code debt at least stays roughly where you left it. Documentation debt gets worse without anyone touching the docs, because the product keeps moving underneath them. A help centre that was accurate a year ago and has been left completely alone since is now wrong in proportion to how much you shipped - which is to say, in proportion to how well the year went.
What a staleness signal actually looks like
The fix is not writing more. It is making decay visible, which means attaching documentation validity to an event that already happens.
That event is the merge. Every pull request that changes user-facing behaviour is, in principle, a claim that some paragraph somewhere is now out of date. The information is right there in the diff - a renamed setting, a moved button, a removed step - and it is thrown away every single time.
So use it. Compare what changed in the code against what the published articles claim, and put the mismatches in a queue where somebody sees them. The article does not have to rewrite itself for this to be worth doing. Knowing which four of sixty articles are now suspect is most of the value, because it converts an unbounded chore into a short, finite list.
That is the shape of the thing we build. It is also, I think, the shape of the answer whether or not you use us.
Three ways a staleness alarm goes wrong
Three places, and I would rather name them than have you find them.
Most merges do not invalidate anything. Refactors, dependency bumps, internal renames and performance work all touch code no user description depends on. A naive "code changed, therefore docs are stale" alarm is mostly noise, and noise is worse than silence: an alert that cries wolf four times a week gets muted in a fortnight, and then you have neither a signal nor the belief that you need one.
Second, staleness detection only catches drift. It cannot tell you an article was wrong the day it was written, or that the article your users most need does not exist at all. Those are coverage problems, and they need a different instrument.
Third, a stale article usually still beats no article. If the sequence is right and one label has changed, most people muddle through. It is worth keeping that in proportion - the goal is a shorter list of known-suspect pages, not a purge.
What to do on Monday
Open your help centre, sort by oldest, and read the top five against the current product. Count how many are wrong.
That number is your interest payment. You have been paying it for a while.
About the Author
Simon Moxon has been building SaaS companies since 2009. He's scaled teams to 20+ people, hit £2m ARR, and learned most of the lessons the hard way. Now he's building SupportPages.io - help docs that write themselves when you ship code. He writes about what's changed in SaaS and what hasn't.