Documentation as a Leadership Practice
I have a rule on my team: if only one person can do it, it's not done. The work might be complete in the sense that the ticket is closed and the system is running, but if the knowledge lives exclusively in one engineer's head, we haven't actually reduced risk. We've just relocated it from "the system might fail" to "this person might be unavailable."
Documentation is how we distribute that risk, and in our environment, it's not a housekeeping task that we get to when things are slow. It's a leadership priority that I protect and include in our planning the same way I protect production stability (and the same way I make other team work visible to leadership).
The Real Cost of Tribal Knowledge
In infrastructure, tribal knowledge accumulates naturally. Systems get built by individuals. Those individuals develop deep context about decisions, workarounds, failure modes, and environmental quirks that never get written down because they're "obvious" to the person who lived through them. This is fine until that person takes vacation during an incident, changes roles, or leaves the company.
I've been on both sides of this. Early in my career, I was the knowledge silo. It felt like job security (I'm the only one who knows how this works). In hindsight, it was fragility wearing the mask of indispensability. Now, as a manager, every knowledge silo on my team is a risk I need to mitigate. Not by diminishing the expert, but by ensuring their expertise is accessible to others even in their absence.
What Good Documentation Looks Like
The documentation that actually gets used (as opposed to the documentation that exists in a wiki collecting dust) has specific characteristics. In our environment, the pattern that works looks like this:
| Characteristic | Why It Matters |
|---|---|
| Task-oriented (not system-oriented) | Engineers search for "how do I do X" not "tell me about system Y" |
| Runbook format with numbered steps | Under pressure, people follow procedures. |
| Includes decision points and escalation paths | Real procedures aren't linear. Document the branches |
| Variables are parameterized, not hard-coded | A doc with hard-coded IPs is useless the moment anything changes |
| Last-verified date visible | Trust erodes when you don't know if the doc was tested this year or three years ago |
The worst documentation is the kind that exists but can't be trusted. A wiki full of outdated procedures is worse than no wiki at all because it gives a false sense of coverage while actively misleading the people who try to follow it.
Making It Happen Without Mandates
Here's the challenge: nobody became an infrastructure engineer because they love writing docs. The intrinsic motivation isn't there for most of the team. Mandating documentation through policy (e.g. "every ticket must have a doc attached") produces grudging compliance and low-quality output. What works better, in our experience, is creating conditions where documentation happens naturally.
We build documentation time into project estimates. If a project takes 40 hours of engineering work, the estimate includes 4-8 hours for documentation and knowledge transfer. It's part of the definition of done.
We use documentation as an onboarding tool. When a new engineer joins, their first assignment is to follow existing runbooks and flag anything that's unclear, missing, or wrong. This produces immediate feedback on doc quality and gives new engineers a way to contribute from day one.
We celebrate doc contributions in the same way we celebrate shipped features. The engineer who writes a clear, tested runbook for a critical process deserves the same recognition as the engineer who built the process in the first place.
The Leadership Dimension
Documentation isn't a technical practice, it's a leadership practice for me. The decision to prioritize it (to spend engineering time on writing instead of building, to slow down project delivery slightly in exchange for institutional knowledge capture) is a strategic choice that only a manager can make and protect.
My role in this isn't to write the docs. It's to create the environment where writing docs is valued, expected, funded with time, and rewarded with recognition. It's to push back when pressure to deliver faster threatens to cut documentation from scope. It's to model the behavior by keeping my own communications structured, complete, and referenceable.
All of this goes to say, if your team has knowledge silos, the problem isn't that engineers don't want to document. The problem is that the system hasn't made documentation easy, expected, and valued. It's the same lowest common denominator thinking I apply elsewhere: absorb the friction upstream so the team can focus on the work that matters. That's a leadership failure, not an individual one, and it's one that compounds until you either fix it proactively or pay for it reactively during the worst possible moment.