Your Documentation Is Lying to You (And So Is Everyone Else's)
There is a particular genre of IT documentation that exists in almost every organization, and it is a work of pure fiction. It lives in a SharePoint folder that was last updated during a previous administration, references systems that were decommissioned two years ago, and was written by someone who has since left the company. It is thorough, professionally formatted, and approximately as useful as a map of a city that has since been entirely rebuilt. Every IT team has it. Nobody talks about it directly. And every time a new person joins the team and tries to follow the runbook, something breaks in a way the documentation specifically said it wouldn't.
The documentation problem is one of those issues that is universally acknowledged and almost universally unaddressed, because maintaining documentation is the kind of work that feels less urgent than literally everything else until the moment it becomes the most urgent thing imaginable. That moment usually involves an outage, a departing colleague, an audit, or some combination of all three arriving simultaneously on a Wednesday afternoon. The engineer who built the critical system three years ago has left. The system has been modified seventeen times since then. The documentation reflects the original build and none of the modifications. This is not a hypothetical scenario. This is a heritage tradition in IT departments everywhere.
The instinct is to declare a documentation sprint, block out a week, and get everything written down properly once and for all. That instinct is well-meaning and almost always doomed. Documentation debt works like financial debt: you cannot pay it all off in one dramatic gesture, and the interest keeps accumulating while you are working on the principal. The organizations that actually maintain good documentation do it through small, consistent habits baked into existing workflows rather than heroic catch-up efforts. Document as you build. Update the runbook when you change the process. Make the pull request include the documentation update, not just the code change. Treat undocumented changes the same way you treat security vulnerabilities: as technical debt with a real cost attached to it.
The other documentation problem nobody likes to discuss is the knowledge that never gets written down at all because it lives entirely inside one person's head. Every IT team has a person like this, the one who knows why the legacy system does the weird thing on the third Tuesday of every month, the one who remembers which vendor contact actually picks up the phone, the one who was in the room when the architecture decision was made and knows the context that explains why the current setup looks the way it does. That person is an extraordinary resource right up until the moment they give notice, at which point they become an organizational emergency. The knowledge transfer that happens in their final two weeks is not adequate. It never is. The time to document what they know is while they still work there.
Good documentation is not a bureaucratic exercise. It is an act of professional generosity toward every person who will ever have to work in the environment you are building. It is the difference between a 2 a.m. incident that gets resolved in twenty minutes and one that runs until sunrise because nobody wrote down the failover procedure. It is the difference between a smooth team transition and a months-long reconstruction project. And it is, not incidentally, one of the clearest indicators of whether an IT organization is genuinely mature or just experienced. Write the thing down. Update it when it changes. Future you, and everyone who comes after you, will be unreasonably grateful.
