I write nearly everything down, and I want to defend that habit with counts rather than sentiment, because "documentation matters" is the kind of sentence everyone nods at and nobody funds.
What exists, counted from the repositories: roughly seventy runbooks across three repos. 4,086 lines of runbook prompt. 985 lines of operational docs. Seven flow diagrams and eighteen user stories written back from an approval engine's code, alongside its eleven documented error codes. A table of contents where every entry carries a blast-radius label. That is not a documentation culture I inherited. It is one I built, procedure by procedure, for reasons that are entirely selfish and entirely practical.
A head is a single point of failure with a holiday schedule
The starting condition was that a large number of fiddly procedures lived in exactly one head — mine. How to reconstruct a failed booking from its logs. How to query a database the standard client cannot reach. Which order a multi-repo feature has to merge in.
A procedure that lives in one person's head has the same shape as any other single point of failure, with one extra property: it takes holidays. Every uptime conversation we have about services, we should be having about knowledge. Nobody would ship a system where one process holds all the state and cannot be restarted; we routinely ship teams built exactly that way. The writing habit is, at bottom, just redundancy engineering applied to the part of the system that goes home at night.
The moment the runbook became the tool
The habit stopped costing willpower the day the runbook and the tool that runs it became the same file. A slash command is a markdown file whose body is the prompt; there is no separate wiki page to keep in sync, because the document is the executable. Writing the procedure down is not preparation for shipping the automation. It is shipping the automation.
That collapse dissolved the classic objection to documentation — "I'd rather spend the time building the tool" — because there is no longer a difference to choose between.
What actually gets read
Documents get read for exactly two reasons, in my experience: either running the document does the job, or the document is indexed by the danger it carries.
The first category is the runbooks. Nobody reads them recreationally; they read them by executing them, which is the only kind of reading that keeps a document alive.
The second category is why the table of contents carries blast-radius labels — 🟢 read-only, 🟠 writes, 🔴 deploys. In one pack that comes to seventeen commands that only read, six that write to the production database, and one that deploys. The label sits in the index, not buried in the body, because the moment someone needs it is the moment they are scanning a list of forty things wondering which one can hurt them. Danger is the one metadata people reliably look up.
What rots
The failure mode is just as identifiable: a document nobody runs. A wiki page describing a process, written after the fact, executed by no one — that page is wrong within months and nobody finds out, because finding out would require someone to follow it. Its wrongness has no trigger. An executable runbook fails loudly the first time the world drifts out from under it, and gets fixed, because the person it failed for needed it to work. Rot is not a function of age. It is a function of execution frequency, and a document with an execution frequency of zero is already rotting on the day it is published.
The eighteen user stories and seven flow diagrams written back from the approval engine's code are my hedge for the category that cannot be executed: description. They were derived from the code, not from memory of intentions, which at least pins them to something checkable — when the code and the diagram disagree, there is a definite artifact to re-derive from.
The section I refuse to delete
Every audit-style document I write ends with a required section: what I am not certain of. It is the least comfortable paragraph to write and the most valuable one to read.
The reasoning is about failure propagation. A document earns trust as a whole; it loses trust as a whole too. The fastest way to destroy one is for a later reader to discover that a number they treated as a measurement was actually an estimate — after that discovery, every other claim in the document is suspect, including the correct ones. One clearly labelled paragraph of uncertainty is cheap insurance against that collapse. It converts "this document might be wrong anywhere" into "this document told me exactly where it might be wrong".
The number that is not here
Consistent with that section: there is no hours-saved figure in this post, because none exists. I never measured the time this habit costs or the time it returns, and I am not going to synthesise a flattering ratio out of vibes.
What I can offer is the same kind of claim as everything above — countable, re-derivable. The runbooks exist. The line counts are real. The procedures that lived in one head now live in files, and this year, for the first time, the answer to an operational question was more often a link than a paragraph I typed out again from memory. I did not measure that either. But you can ask anyone who used to have to ask me.