Your best engineer just quit. Now what?

Every engineering team has a person who knows why the deployment pipeline works the way it does, why the database schema has that strange naming convention, what happened during the outage in 2023 that shaped the current monitoring setup, and which parts of the legacy codebase are load-bearing walls that absolutely must not be touched.

When that person leaves, and eventually they will, all of that context leaves with them. The team discovers the gaps over the following weeks and months, one painful incident at a time: a deployment that breaks because nobody knew about the manual step that wasn't documented, a refactor that inadvertently removes a workaround that existed for a reason nobody can now remember, a new hire who spends three weeks trying to understand a system that the departed engineer could have explained in twenty minutes.

This is the bus factor problem, named for the morbid question "how many team members would have to be hit by a bus before the project couldn't continue?" Most engineering teams have a bus factor of one or two for significant parts of their system, which means one or two departures could cause weeks or months of disruption.

What actually leaves

When a knowledgeable engineer departs, the code stays. The PRs stay. The Slack messages stay, at least until they scroll off the retention window. What leaves is the interpretive layer: the understanding of why things are the way they are, which decisions were conscious trade-offs and which were accidents, where the bodies are buried, and what will break if you touch the wrong thing.

This is tribal knowledge in its most concentrated form, and it's the kind of knowledge that's hardest to transfer because the person who holds it often doesn't realise how much they know. They've accumulated it over months or years of working closely with the system, and much of it has become so automatic that they couldn't produce a comprehensive document of it even if they tried.

Exit interviews and knowledge transfer sessions help, but they capture a fraction of what the departing person knows. You can't transfer two years of accumulated context in a two-week notice period.

The continuous capture alternative

The answer to the bus factor problem is capturing knowledge continuously rather than scrambling to extract it at the point of departure.

Self-writing documentation does this by converting the engineering activity that's already happening into structured, searchable documentation as it happens. When an engineer explains a design decision in a Slack thread, that explanation is captured and integrated into the system's documentation. When a PR includes a description of why a particular approach was chosen, that reasoning is preserved alongside the code. When a meeting discusses the trade-offs of a migration plan, the discussion is documented and linked to the relevant system.

The knowledge isn't extracted from the engineer in a special session. It's captured as a byproduct of the work they're already doing, which means it accumulates continuously and stays current as the system evolves.

When that engineer eventually leaves, the documentation they generated over their tenure remains. The next person who needs to understand why the deployment pipeline works the way it does can search the docs rather than discovering the answer through trial and error.

The cost of not solving this

The cost of a key departure without adequate documentation is difficult to measure precisely but easy to feel. Teams typically report two to six months of reduced velocity after losing a critical knowledge holder, depending on how much of the system that person understood and how well the knowledge was documented.

At a senior engineering salary of $180,000-$220,000, even two months of meaningfully reduced productivity across a team represents tens of thousands of dollars in lost output. For critical systems where the departed engineer was the sole knowledge holder, the cost can be much higher: production incidents that take longer to resolve, features that are deferred because nobody understands the system well enough to modify it safely, and onboarding that takes months rather than weeks because there's nothing for new hires to read.

The bus factor problem is one of the few engineering risks where the solution (documentation that captures knowledge continuously) is cheaper than the problem it prevents.

Frequently asked questions

Can't we just do knowledge transfer sessions? You can and should, but they capture only what the departing engineer thinks to mention, which is a fraction of what they know. Much of the most valuable knowledge is contextual and only surfaces in response to specific situations that don't arise during a transfer session.

How much documentation is enough to reduce the bus factor? Focus on decisions and reasoning rather than implementation details (the code documents itself at the implementation level). If a new engineer can understand why the system is structured the way it is by reading the docs, the bus factor risk is substantially reduced.

Does this apply to small teams? Small teams are actually more vulnerable, because each person holds a larger proportion of the total knowledge. A five-person team losing one engineer loses 20% of its collective context. A fifty-person team losing one engineer loses 2%.

Related reading: The hidden cost of tribal knowledge, Documentation debt, Your codebase is documented, your decisions aren't. Related pages: Self-writing docs, Knowledge retention, For engineering teams.