Bus factor and knowledge sharing

Overview

All the previous lessons of this module converge here. Living documentation, docs-as-code, the C4 + ADR + arc42 system, the stable-vs-volatile rule, the onboarding README —all of it exists, at bottom, for one single thing: so the system's knowledge doesn't depend on a single head. This lesson makes that objective explicit and measures it with the metric that captures it: the bus factor. Lesson 1 introduced it; this one takes it all the way. You're going to simulate what happens when a specific person leaves Mercado —what modules are left orphaned—, identify the single points of failure, and compare the different insurances against that risk, measuring which costs less. The conclusion, measured, is the thesis of the whole module: documenting the stable is the cheapest insurance against the knowledge leaving when a person leaves.

The underlying idea is to treat knowledge as a risk that gets insured, not as something that simply "is there". A module that a single person understands is a concrete risk —the day that person leaves, the module is left with no owner— and, like any risk, it can be reduced by paying a premium. There are two possible premiums: documenting the stable of the module (cheap: you write its boundaries and decisions once) or training a second human owner through pairing or rotation (expensive: weeks of someone else learning the module by working it). Both raise the bus factor from 1 to 2, but they cost different orders of magnitude. This lesson executes that comparison and shows why documentation wins as insurance —with an honest nuance that the lesson underlines: the doc doesn't replace the human, because the human does something the doc can't—.

Connection with the module. It's the synthesis lesson: it gathers everything before it and puts it at the service of the bus factor. Living documentation and docs-as-code (lessons 2-3) are how the doc that raises the bus factor is kept alive; the C4+ADR+arc42 system (lesson 4) is what pieces compose it; the stable vs the volatile (lesson 5) is what gets documented so the insurance is cheap; the README (lesson 6) is the bus factor of the operational knowledge. Everything points here. With the module's analogy: it's the written recipe that survives the grandmother no longer being there —the knowledge that stays when the person leaves—. Frontier with the rest: people management in depth (retention, succession plans, 1:1s) is management and stays out; here only the knowledge↔documentation dynamic and its economics as insurance.

An analogy: the written recipe that survives the grandmother

Think of a family and the dish that makes its gatherings unforgettable —the mole, the paella, the stew everyone waits for— and of two ways that knowledge lives.

The recipe that's only in the grandmother's hands. The grandmother makes the stew from memory, as she learned it from her mother: a handful of this, "until it looks like this", the exact point she recognizes with her eye and nose. She never wrote it down —she didn't need to, she was always there—. The whole family takes for granted that the stew is the grandmother's, that there will always be stew because the grandmother is always there. And then the grandmother is no longer there. And with her the stew is gone: no one knows the proportions, no one recognizes "the point", the attempts to reproduce it come out similar but never the same, and over the years the exact flavor is lost forever. It wasn't lost because no one cared; it was lost because the knowledge lived in a single head and that head left. The stew had bus factor 1.

The written recipe that survives. Another family, with the same grandmother and the same stew, does something different in time: one afternoon, they sit down with her and write the recipe —the exact proportions, how to recognize "the point", the tricks she takes for obvious—. It's not the same as the grandmother (she improvises, adjusts, has an instinct no recipe fully captures), but it's the stable part of the stew: what doesn't change, what can be transmitted. When the grandmother is no longer there, the stew survives: the family makes it with the recipe, it comes out well, and —this is what matters— they can teach it to the next generation, who will teach it to the next. The knowledge stopped depending on a single person. The stew no longer has bus factor 1.

Here's the whole lesson: writing the recipe doesn't replace the grandmother —her instinct for improvising left with her—, but it saves the essence of the stew from dying with her. The grandmother is Elena; the stew is the payments module; the written recipe is the documentation of the stable. As long as Elena is there, the recipe isn't needed —she knows— and that's why it's so tempting not to write it ("Elena knows payments anyway"). But that comfort is the trap: the day Elena leaves, if no one wrote the recipe, payments is left like the lost stew —no one knows why it's built this way, what "the point" is, what decisions hold it up—. Writing the recipe in time —documenting the stable of payments before Elena leaves— is what makes the knowledge survive. This lesson measures why writing the recipe is much cheaper than training another grandmother, and why, as insurance, it's the best investment.

Worked example: who leaves, what is orphaned, and which insurance costs less

We're going to do three measured things. First, simulate what Mercado modules are left orphaned if each person leaves —to find the single points of failure—. Second, identify the modules at risk (bus factor 1). Third, compare the cost of two insurances to bring those modules to bus factor ≥ 2: documenting the stable against training a second human owner. The knowledge map now has six modules (we add search, which a single person also maintains):

# Bus factor and knowledge sharing. We simulate who leaves and what modules are left
# ORPHANED (with no one who knows how to maintain them). A module with a single knower is a
# single point of failure. Then we compare two insurances against that: document the
# STABLE (cheap) vs add a second human owner via pairing/rotation (expensive).
OWNERSHIP = {
    "catalog":  {"Ana", "Beto", "Caro"},
    "orders":   {"Beto", "Diego"},
    "payments": {"Elena"},
    "shipping": {"Diego", "Caro"},
    "platform": {"Ana", "Elena", "Beto"},
    "search":   {"Caro"},
}
PEOPLE = sorted({p for owners in OWNERSHIP.values() for p in owners})

# 1) If this person leaves today, what modules are left orphaned?
print("== Simulation: who leaves -> what is orphaned ==")
for person in PEOPLE:
    orphaned = [m for m, owners in OWNERSHIP.items() if owners - {person} == set()]
    tag = ", ".join(orphaned) if orphaned else "-"
    print(f"  {person:<6} leaves -> orphaned: {tag}")
print()

# 2) Modules at risk today (bus factor <= 1): single points of failure.
at_risk = [m for m, owners in OWNERSHIP.items() if len(owners) <= 1]
print(f"Modules at risk (bus factor 1): {', '.join(at_risk)}  ({len(at_risk)})")
print()

# 3) Two insurances to bring EACH at-risk module to bus factor >= 2:
DOC_DAYS = 2      # document the stable (boundaries + decisions) of a module
PAIR_DAYS = 15    # train a second human owner via pairing/rotation
doc_cost = len(at_risk) * DOC_DAYS
pair_cost = len(at_risk) * PAIR_DAYS
print("Cost of insuring the at-risk modules (bringing them to bus factor >= 2):")
print(f"  document the stable: {len(at_risk)} x {DOC_DAYS}d = {doc_cost} days")
print(f"  second human owner:  {len(at_risk)} x {PAIR_DAYS}d = {pair_cost} days")
print(f"  doc is {pair_cost / doc_cost:.1f}x cheaper as INSURANCE.")
print()
print("Doc doesn't replace the human (the human evolves the module); but as")
print("INSURANCE against a single head carrying the knowledge away, it's the cheapest.")

What to expect. Running the file, the output is exactly this:

== Simulation: who leaves -> what is orphaned ==
  Ana    leaves -> orphaned: -
  Beto   leaves -> orphaned: -
  Caro   leaves -> orphaned: search
  Diego  leaves -> orphaned: -
  Elena  leaves -> orphaned: payments

Modules at risk (bus factor 1): payments, search  (2)

Cost of insuring the at-risk modules (bringing them to bus factor >= 2):
  document the stable: 2 x 2d = 4 days
  second human owner:  2 x 15d = 30 days
  doc is 7.5x cheaper as INSURANCE.

Doc doesn't replace the human (the human evolves the module); but as
INSURANCE against a single head carrying the knowledge away, it's the cheapest.

Read the simulation first, because it reveals where the real risk is, which isn't where you'd expect.

The simulation: only two departures leave a module orphaned. Notice the pattern. If Ana, Beto, or Diego leaves, no module is left orphaned —"orphaned: -"—: the modules they maintain have other knowers who hold them up. But if Caro leaves, search is orphaned (Caro is its only owner); and if Elena leaves, payments is orphaned. This is revealing: of five people, only two are single points of failure, and not for being the "most important" in general, but because they're the only ones holding up a module. The bus factor risk isn't spread evenly across people —it concentrates in whoever is the sole owner of something—. And notice that Elena appears in two modules (payments and platform), but only leaves payments orphaned: platform has Ana and Beto to hold it up. Being a knower of many modules doesn't make you a single point of failure; being the only knower of one does. The risk is in the exclusivity, not the quantity.

The modules at risk: payments and search, bus factor 1. The simulation identifies exactly two modules at risk —the ones a single person maintains—. These are the ones to insure; the other four already have backup. Notice the efficiency of the diagnosis: you don't have to "improve the documentation in general", you have to insure two concrete modules. The bus factor tells you exactly where to put the effort —on the bottlenecks, not spread out—.

The insurance comparison: the doc is 7.5x cheaper. To bring each at-risk module to bus factor ≥ 2, there are two paths. Documenting the stable of payments and search —their boundaries and decisions, the "recipe"— costs about 2 days per module, 4 days total. Training a second human owner through pairing or rotation —another person learning payments and search by working them until they can maintain them alone— costs about 15 days per module, 30 days total. Documentation is 7.5 times cheaper as insurance. With 4 days of work you eliminate the system's two single points of failure; with the human path, you'd spend almost a month-and-a-half-person for the same bus factor.

And the honest nuance, in the last line, which prevents the dangerous misunderstanding. The program says it clearly: "doc doesn't replace the human (the human evolves the module)". Documenting payments doesn't make it as maintainable as having two human experts —a human can evolve the module, make new decisions, improvise against what the doc didn't foresee, like the grandmother adjusting the stew—. The doc captures the stable (the recipe), not the living instinct. So why does the doc win? Because as insurance —as protection against the specific risk that the knowledge is lost when the person leaves— the doc is unbeatably cheap and sufficient: it prevents payments from being orphaned (with no one who understands it) for a fraction of the cost. The lesson isn't "document instead of training people"; it's "document the stable as cheap insurance and train people where you need active evolution". For the risk of losing the knowledge, the doc is the right insurance; to have a module with active owners who grow it, you need humans. They're complementary, not substitutes —and the mistake is having neither of the two and trusting that Elena never leaves—.

As a diagram, the risk and its insurance look like this:

Knowledge risk in Mercado (who is a single point of failure)
  Caro  ── sole owner of search   ─┐
  Elena ── sole owner of payments ─┴─> 2 modules at bus factor 1

Two insurances to raise to bus factor 2:
  document the stable    ████ 4 days      <- cheap, prevents orphaning
  second human owner     ██████████████████████████████ 30 days
                         the doc is 7.5x cheaper as INSURANCE

Deep dive: knowledge as an insurable risk

The experiment treated knowledge as a risk that gets insured. It's worth developing that lens, because it changes how an architect thinks about documentation —from "a good practice it'd be nice to have" to "a risk-management decision with clear economics"—.

Let's start with why bus factor 1 is so tempting to leave as is, because understanding the temptation is half the cure. While the person is there, the knowledge concentrated in them is more efficient, not less: nothing has to be documented, no one else has to be taught, you ask and they answer instantly. A team that optimizes for today's speed naturally lets knowledge concentrate —it's the path of least effort—. The cost of bus factor 1 doesn't exist while the person is there; it appears all at once the day they leave, and by then it's too late to write the recipe (the grandmother is no longer there to dictate it). This temporal asymmetry —immediate benefit of concentrating, deferred and sudden cost of the departure— is exactly the structure of an uninsured risk: you save the premium while nothing happens, and you pay it all at once when it does. The architect's discipline is to pay the premium early, while the person is still there to dictate the recipe.

Now, why documentation is such good insurance for this specific risk. The bus factor risk isn't "the module stops working" —the code keeps running when Elena leaves—; it's "no one understands the module enough to maintain, change, or fix it safely". That understanding has two layers: the stable (why it's this way, what its boundaries are, what decisions hold it up —the recipe—) and the living (the instinct to evolve it against the new —the grandmother improvising—). Documentation captures the first layer cheaply and perfectly, and that's the layer that gets lost most and costs most to reconstruct: reconstructing the why of a decision no one documented can take weeks of archaeology in the code and still remain conjecture. The second layer, the living instinct, the doc doesn't capture —but that one recovers faster if you have the first: a new dev with good doc of the stable of payments can become a competent owner in days, because they don't have to rediscover the why; it's already written—. The doc doesn't prevent you from needing people; it makes training new people cheap, because it starts from a recipe instead of zero. That's why doc of the stable is the right insurance: it covers exactly what gets lost most and makes recovering the rest cheap.

From there comes the relationship between the knowledge-sharing mechanisms, which is worth ordering because they don't compete but complement each other. Documentation of the stable is the base insurance: cheap, permanent, doesn't depend on anyone being there. Pairing and rotation (two people working a module together, or people rotating between modules) build the living knowledge in more than one head: more expensive, but it gives active owners who evolve the module. Code reviews spread knowledge little by little, as a side effect of normal work. A mature team uses all three: documents the stable of everything (universal cheap insurance), and applies pairing/rotation where it needs redundant active owners (the critical modules that evolve fast). The mistake isn't choosing badly among them; it's using none and letting each module depend on a head. And within that mix, documentation is what makes everything else cheaper: with good doc of the stable, pairing is faster (the learner starts from the recipe), rotation is less risky (whoever arrives has a map), and onboarding doesn't depend on anyone (lesson 6).

A nuance about the metric itself, to use it with judgment. The bus factor is a useful approximation, not an exact truth: "knowing a module" isn't binary (there are degrees of understanding), and the model simplifies. But its value isn't in the precision of the number, but in what it forces you to see: that the knowledge risk concentrates in whoever is the sole owner of something, and that this risk is invisible until it materializes. Use the bus factor as a radar for single points of failure —to find the modules that depend on one head and insure them before that head leaves—, not as a vanity metric to be maximized in the abstract. Raising a healthy module's bus factor from 3 to 4 is worth nothing; raising payments' from 1 to 2 eliminates a single point of failure. The radar tells you where, the economics tell you with which insurance (almost always, start with doc of the stable).

Common mistakes

Trusting the person will never leave (not insuring the risk). What happens: the team knows only Elena understands payments, but leaves it that way —"Elena won't leave", or it simply isn't thought about— because while Elena is there everything works and asking is faster than documenting. The day Elena announces she's leaving, there's a month of panic trying to extract everything she knows. Why it happens: bus factor 1 is more efficient in the short term (it costs nothing while the person is there), and its cost is deferred and invisible until the departure. How to spot it: if there are modules that "only so-and-so understands" and no one treats it as a problem, if the team panics when that person goes on vacation, you're trusting they'll never leave. How to fix it: treat every bus factor 1 as a risk to insure now, while the person is there to dictate the recipe —documenting the stable of the module is the cheapest insurance—; the premium is paid before, not after.

Believing documenting replaces training people (or vice versa). What happens: a team documents the stable and concludes "done, we no longer depend on anyone" —forgetting that the doc doesn't evolve the module, that active owners are still needed for that—; or the reverse, a team does pairing and rotation but documents nothing, and when both people who knew a module leave, the why is lost anyway. Why it happens: documentation and training people are thought of as substitutes that compete, when they're complements that cover different things (the stable vs the living). How to spot it: if you justify not documenting by saying "we do pairing", or not training owners by saying "it's documented", you're treating complements as substitutes. How to fix it: use both —documenting the stable as universal base insurance (cheap), and pairing/rotation where you need active owners who evolve the module—; the doc makes the stable cheap to preserve, people make the living possible to evolve.

Maximizing the bus factor in the abstract (losing the radar). What happens: the team, taking the bus factor as a metric to maximize, invests in raising the bus factor of modules that are already healthy (from 3 to 4) or in documenting everything equally, instead of attacking the concrete single points of failure. It spends effort where there's no risk. Why it happens: the metric (a radar to find risk) is confused with a goal (a big number is good). How to spot it: if you're documenting or training people on modules that already have several owners while leaving a bus factor 1 untouched, you lost the radar. How to fix it: use the bus factor to locate the bottlenecks (the modules with a single owner) and concentrate the insurance there; raising a healthy module doesn't reduce the system's risk (which is set by the weakest, as we saw in lesson 1). The goal isn't a high average bus factor, it's that no critical module is at 1.

Exercises

Exercise 1 — Why Elena in two modules leaves only one orphaned. In the simulation, Elena is a knower of two modules (payments and platform), but when she leaves only payments is orphaned, not platform. Explain why, and what this tells you about where the bus factor risk really lives.

See solution

Elena leaves only payments orphaned because she's the sole owner of payments, but not the sole owner of platform. When she leaves, payments is left with no one who knows it (she was its only owner) → orphaned; but platform still has Ana and Beto, who keep holding it up → not orphaned. What determines whether Elena's departure leaves a module orphaned isn't how many modules Elena knows, but in which ones she's the only knower. Knowing platform alongside two others creates no risk; being the only one who knows payments does.

This reveals where the bus factor risk really lives: in the exclusivity, not the quantity of knowledge. A person who knows many modules but is always accompanied by others isn't a single point of failure in any of them —their departure leaves nothing orphaned—. A person who's the only one who knows a single module is one. The risk isn't measured by "how much the person knows" (which is the common intuition: "Elena knows a ton, she's a huge risk") but by "what she's the only one who knows". The practical consequence: to reduce the bus factor risk you don't worry about the people who know the most in general, but about identifying each module with a single owner and insuring that module —giving it a second knower or documenting the stable—. The radar points at the exclusive modules, not the wise people.

Exercise 2 — The right insurance for each layer. The text distinguishes two layers of a module's knowledge: the stable (the why, the boundaries —the recipe—) and the living (the instinct to evolve it —the grandmother improvising—). For each layer, say which mechanism protects it best (documentation / pairing-rotation), and explain why documentation wins as "insurance" even though it doesn't capture the living layer.

See solution

The stable (the why, the boundaries) is protected best by documentation. This layer is exactly what an ADR and the boundary description capture: why payments is separate, what contracts it exposes, what decisions hold it up. It's information that changes little (stable) and that the doc preserves cheaply and perfectly. And it's the layer that gets lost most when the person leaves, because the why isn't in the code —reconstructing it without doc is slow, conjectural archaeology—. Documenting the stable is the right insurance for this layer: cheap, permanent, and it covers what would cost most to recover.

The living (the instinct to evolve the module) is protected best by pairing/rotation. This layer —making new decisions, improvising against what the doc didn't foresee, growing the module— can't be written in a recipe, because it's real-time judgment. It's only transmitted by working the module alongside another person (pairing) or rotating people through it, until more than one head has the instinct. To have redundant active owners who evolve payments, you need humans, not doc.

Why the doc wins as insurance even though it doesn't capture the living layer: because the specific risk the bus factor insures is that the knowledge is lost when the person leaves, and the layer that gets lost most and costs most to reconstruct is the stable (the why) —precisely the one the doc captures cheaply—. The living layer, in contrast, recovers faster if you have the stable documented: a new dev with good doc of the why of payments becomes a competent owner in days, not weeks, because they don't have to rediscover the why. So the doc not only insures the stable layer directly; it also makes recovering the living layer cheaper. As insurance against the loss of knowledge, the doc covers the essential for a fraction of the cost. What the doc doesn't do is replace having active owners —for continuous evolution humans are still needed—, but that's a different goal (having the module well tended) from the one the bus factor insures (that the knowledge doesn't die with a departure). Each mechanism for its layer; the doc for the stable, the people for the living; and the doc first because it's the cheapest insurance of what gets lost most.

Exercise 3 — The premium paid early. The text says bus factor 1 is "an uninsured risk" whose premium must be paid before the person leaves. A manager responds: "but documenting payments now costs time we need for features; better we document it if someday Elena announces she's leaving". Explain why that strategy fails, using the grandmother analogy and the temporal structure of the risk.

See solution

The strategy fails because the best time to write the recipe is while the grandmother is still there, and "if someday she announces she's leaving" tends to be too late or of very poor quality. Think of the temporal structure of the risk: bus factor 1 costs nothing while Elena is there (which is why it's tempting to leave it), and its cost appears all at once when she leaves. The manager's strategy —"we document when Elena announces"— assumes there'll be a comfortable moment, between the announcement and the departure, to extract all her knowledge. But that moment is bad for three reasons. First, it may not exist: people sometimes leave abruptly (an offer with an immediate start, an illness, a conflict), with no useful notice period. Second, even with notice, that period is saturated with rushed handover and Elena already has one foot out the door —documentation done under departure pressure is incomplete and low quality, compared to what's written calmly while the knowledge is used daily—. Third, and most subtle: much of Elena's knowledge is tacit —things she takes for obvious and doesn't even remember she knows—, and that only surfaces by writing it while she works the module normally, not in a "dump everything you know" session that the brain can't do on demand.

It's exactly the grandmother: the family that waits for the grandmother to "announce" she's leaving to write the recipe discovers there was no notice (she left abruptly), or that in the rush the recipe came out incomplete, or that the grandmother, pressured to dictate from memory in one afternoon, forgot the tricks that only came out while cooking. The family that wrote the recipe in time —a calm afternoon, cooking together, with the grandmother in full form— captured the stable well. The insurance premium is paid before precisely because the risk, when it materializes, leaves no time to insure yourself: you can't buy fire insurance when the house is already in flames. Documenting the stable of payments now —4 days, cheap— is paying the premium while you can; waiting for Elena to announce is betting there'll be time and quality to do it later, and that bet is lost often. And the cost of losing it —payments orphaned, weeks of archaeology, decisions undone through ignorance— is much greater than the premium you tried to save.

Summary and next step

In this lesson you took to the bottom the idea that holds up the whole module: that the knowledge doesn't depend on a single head, measured with the bus factor. You simulated who leaves Mercado and saw that the risk concentrates in whoever is the only owner of a module —only Caro (search) and Elena (payments) leave something orphaned, and Elena in two modules leaves only one orphaned, because the risk lives in the exclusivity, not the quantity—. You compared the insurances to raise the bus factor to ≥ 2: documenting the stable (4 days) against training a second human owner (30 days), and you measured that the doc is 7.5 times cheaper as insurance. With the recipe that survives the grandmother, you understood the key nuance: the doc doesn't replace the human (the living instinct leaves with the person) but it saves the essence from dying with her —and as insurance against the loss of the knowledge, it's unbeatably cheap—. You learned to treat knowledge as an insurable risk, to pay the premium early (while the person is there to dictate the recipe), and to use the bus factor as a radar for single points of failure, not as a metric to maximize in the abstract.

Before moving on you should be able to: explain why the bus factor risk lives in the exclusivity and not the quantity of knowledge; distinguish which layer (stable/living) each mechanism (doc/pairing) protects best and why the doc wins as insurance; and argue why the insurance premium is paid before the departure, not after.

Lesson 8 is the project that closes the module: you take the role of Mercado's architect facing a real scenario —Elena leaves in a month and six new devs join this quarter— and you produce the documentation package that survives: the docs-as-code structure, the README that onboards, the stable decision of payments captured in an ADR so it survives Elena, and the executed report that gives the verdict —is Mercado's documentation ready to survive Elena's departure?—. Everything in the module converges in that deliverable: living documentation, docs-as-code, the C4+ADR+arc42 system, the stable, the README, and this lesson's bus factor, applied to a case that gets measured.

Resources

• Cyrille Martraire, Living Documentation (Addison-Wesley, 2019), on knowledge sharing and bus factor — the canonical development of doc as a mechanism so the knowledge doesn't depend on individuals. In English.
• The concept of bus factor / truck factor (Wikipedia and the software engineering literature) — the origin and variants of the metric, and studies that measure it in real open-source projects. In English.
• Matthew Skelton and Manuel Pais, Team Topologies (IT Revolution, 2019) — on how to structure teams and share knowledge so capacity doesn't depend on individuals; complements the bus factor with the organizational dimension (module 2 of this guide). In English.
• Andrew Hunt and David Thomas, The Pragmatic Programmer, 20th Anniversary Edition (Addison-Wesley, 2019), on knowledge portfolios and not being irreplaceable — the ethics of sharing knowledge instead of hoarding it as power. In English.
• Gene Kim, Jez Humble, Patrick Debois and John Willis, The DevOps Handbook (IT Revolution, 2016), on sharing knowledge (pairing, reviews, documentation) as a practice of organizational resilience. In English.