Software maintenance that survives losing your best engineer
Your best engineer is also your biggest liability. The documentation you asked for probably didn't fix it.
Most teams don't lose critical knowledge to layoffs. They lose it to a vacation, a sick day, or a two-week notice. One engineer understands how the systems that keep the business running behave in practice, and everyone else operates around them. You already saw the risk, so you asked the team to document everything. The gap stayed open. Here's why that happens, and what closes it.
When one person is the system
One engineer understands how the billing engine behaves in production. Not the version in the docs. The real one, with the edge cases and the patch from last spring that never got written down.
The rest of the team follows one rule: don't touch it. Not out of weakness. Touching it without that person means guessing, and guessing in a payment system ends with a client call at 11pm.
Engineers have a name for this. The bus factor: how many people would have to disappear before a project stalls.
When the answer is one, that person stops being a team member and becomes the point everything depends on.
2 in 3
Of more than 100,000 popular open-source projects studied, roughly two-thirds had a bus factor of one or two. 1
1 person
Is all it takes. Losing one or two contributors would leave those projects with no one who understands them.
The fix that fell short
So you did the responsible thing. You told the team to write everything down.
Months pass, the wiki fills up, and the exposure stays exactly where it started. Documentation fails in a specific, predictable way: teams write down what's easy to write, and skip what's dangerous to lose.
They document setup steps. Folder structure. The onboarding checklist. The knowledge a competent new hire would reconstruct in a week anyway.
What never reaches the page is the knowledge that exists only because someone lived through the decision.
The right 20%
Most knowledge genuinely isn't worth capturing. The work lies in identifying the specific slice that walks out the door and never comes back, then moving it out of one head and into a place the team can reach. Reducing key person dependency on an engineering team comes down to which pages get written, and setup guides aren't the ones that matter here.
Five kinds of knowledge account for almost all of it.
Action 01
Why the architecture is the way it is
Every system carries decisions that look strange from the outside. Why this database instead of the obvious one. Why the service was split here rather than there. What matters is the reasoning and the alternatives that got rejected. Without that context, the next engineer either preserves a constraint that no longer applies or breaks something that was load-bearing for a reason nobody remembers.
How to capture it: a short decision record for anything expensive to reverse. One paragraph covering what got chosen, what got ruled out, and the constraint that drove it. Enough that the next person inherits the reasoning along with the result.
Action 02
Which "temporary" workarounds are holding production together
Every mature system has them. The retry that exists because an upstream API lies about its status codes. The hardcoded value nobody dares to parameterize. They work, which makes them dangerous: they look optional. Clean one up without knowing why it exists, and the lesson arrives the hard way.
How to capture it: mark them in the code where they live, with a line explaining what breaks if they get removed. The explanation belongs next to the workaround, not in a document nobody opens.
Action 03
What already broke once, and how it got fixed
The most expensive knowledge in any team comes from the incident that already happened. The outage, the data corruption, the deploy that took the system down. Resolve it and move on without recording anything, and the team pays full price to learn the same lesson again next time.
How to capture it: a lightweight postmortem for anything that caused real pain. What happened, why, and what prevents a repeat. The point is making the fix outlive the person who found it.
ACTION 04
The external dependencies nobody wrote down
The third-party service with the undocumented rate limit. The internal team whose approval gates a certain deploy. The cron job running on a server no one thinks about. These live entirely in the memory of whoever set them up, and they surface at the worst possible moment.
How to capture it: one living map of what the system depends on beyond its own code. External services, credentials, scheduled jobs, human approvals. Tedious to maintain, decisive in a crisis.
ACTION 05
The client decisions that explain why a feature works the way it does
Some of the strangest behavior in a codebase has nothing to do with technology. A requirement a client asked for two years ago that never made it into a ticket. Without that context, the next engineer treats a deliberate business rule as a bug and "fixes" it, straight into a client escalation.
How to capture it: record the business reason alongside the feature, not just the technical spec. A single line about why the rule exists often prevents an expensive misunderstanding.
Sources
- Avelino, G., Passos, L., Hora, A., Valente, M. T. A novel approach for estimating Truck Factors. IEEE International Conference on Program Comprehension (ICPC), 2016. ieeexplore.ieee.org
How we think about this
Capturing the right 20% works as a habit, not a project. A documentation sprint that everyone abandons by week two won't do it. The reasoning behind a decision gets recorded as the decision is made. A workaround gets a comment the moment it's written. The person who understands a system pairs with someone else well before it turns urgent.
That habit is what carries a team through a transition, whether it's a resignation, a leave, or a bad day at the wrong moment. The teams that keep running aren't the ones with the thickest wiki. They're the ones where more than one person can reach what matters.
If continuity depends on a single engineer showing up every day, that dependency is worth closing before the day it gets tested.
See how we approach maintenance and tech supportFrequently asked questions
What's the difference between tacit and explicit knowledge on an engineering team?
Explicit knowledge is anything already written down or reconstructable from the code: setup steps, folder structure, documented processes. Tacit knowledge lives in someone's experience: why a decision was made, which workaround is load-bearing, what broke last year. Tacit knowledge carries almost all the risk when someone leaves, because it exists nowhere except in their head.
How much does it cost when a key engineer leaves?
Beyond recruiting and onboarding, the hidden cost is the time the team spends reconstructing lost context. Industry estimates put the fully-loaded cost of replacing a technical employee at a large share of their annual salary, and filling the knowledge gap left behind can take months of reduced velocity across the whole team, not just the empty seat.
What is tribal knowledge, and why is it a risk?
Tribal knowledge is the unwritten understanding of systems and decisions that only certain people carry. It feels efficient day to day, since asking the person who knows is faster than looking anything up. That same efficiency is the risk: when that person is unavailable, the knowledge is unavailable too, and the team is left guessing on systems it depends on.
