Soundtrack for this blog: Simon & Garfunkel - The Boxer
Over the years, I’ve learned that documentation rarely fails because people don’t care. It fails because no one notices when it quietly stops being true. Teams don’t wake up one morning and decide to let documentation rot. It happens gradually — a decision changes, an exception becomes the norm, a clarification is explained verbally once, then twice, then “everyone just knows.” By the time someone asks whether the documentation is still accurate, it already requires explanation. At that point, it has drifted.
To deal with this, we don’t rely on rigid review schedules or exhaustive checklists. In practice, those tend to be ignored once delivery pressure builds. Instead, we use a lightweight set of prompts that help us recognize when documentation needs attention.
The checklist is deliberately simple. It isn’t tied to any particular tool or system, because documentation problems rarely are. It works just as well for process descriptions, system overviews, or project artefacts. Most importantly, it doesn’t try to replace judgment. It exists to support it. When someone starts explaining the same thing repeatedly, that’s a signal. When decisions need to be reconstructed from memory, that’s another. When new team members struggle to orient themselves, even though “the documentation is there,” it’s usually not a training problem — it’s a documentation one.
The checklist gives us a way to pause and ask a few uncomfortable but useful questions. Does this still reflect how we actually work? Would someone who wasn’t here understand it? Are we relying on people’s heads more than we should? We’re sharing an illustrative version of this checklist because it reflects how we maintain our own documentation. It’s not complete, and it’s not meant to be. Every organization has its own context, constraints, and tolerance for risk. What matters is not the checklist itself, but the habit of noticing when documentation stops doing its job.
Good documentation doesn’t need constant attention. But it does need someone who knows when to look at it again.