During the incident I wrote about recently, a thought hit me once production was back: what if I hadn't been there? Unreachable, or unable to recall the commands I'd just run, no one could have taken over. The system didn't hang on a fragile server. It hung on me.
In reliability, a single point of failure (SPOF) is the component whose failure brings down everything else. Applied to a person, it's simple: if you're the only one who knows, your absence is the outage. That day, the SPOF was me.
A plan is not a state
Before the migration, I had written a document. It described what I was going to do: the plan, the planned steps. On paper, I was covered.
But a plan and a state are two different things. My document said where I wanted to go, not where I was. In the middle of an incident, the only question that matters is the second one: what has already been done, which commands ran, how to roll back. None of that was written down: it lived in my head, and what exists only in one head can't be handed over.
Being irreplaceable is a trap
We often think being the only one who masters a topic is a position of strength. It's the opposite. As long as you're the only one who knows, you're the link whose failure blocks everyone: the slightest absence, a sick day or a holiday, and no one can move forward. And it's not just a risk for the team, it's one for you: you become irreplaceable in the bad sense, the one who keeps things from being delegated and from moving on.
What I changed
I took my document and turned it from a plan into a living state. I added what was missing: the context and the why, the real state of the system, the steps already done with their exact commands, and the rollback procedure. Enough to know at any moment where things stand, and resume cold.
I also went back to my scripts. They worked, but they weren't readable, and above all had not a word on the what and the why. I commented them, then linked them to the document: the document points to the script, the script points back to the document. No more black box. Anyone can now resume cold.
Documenting is also communicating
Writing isn't enough if no one knows at the right time. Documentation is asynchronous communication; there is also communication, plain and simple. The rule I drew from it: scale the communication to the size of the change. Warning everyone about a minor change is noise; warning no one about a high-impact change is a guaranteed incident. Before touching a demo environment, for example, I warn the sales teams: a demo that goes down in the middle of a client meeting is their problem before it's mine. Who is affected decides who you warn, and how far in advance.
What I take from it
Documenting isn't a waste of time. It's what keeps the system, and the team, from depending on my memory or my presence. And paradoxically, ceasing to be indispensable made me more useful: you get trusted with more important things when what you do doesn't leave with you.
I even turned that document into a reusable template, so I don't start from a blank page on the next project.