The hidden cost of tribal knowledge

Tribal knowledge is the informal, undocumented understanding of how things work that exists only in the heads of the people who've been around long enough to acquire it. Why the billing system handles refunds the way it does. Who to talk to about the legacy API. What happened during the incident in March that shaped the current alerting setup. Which configuration values are load-bearing and which are safe to change.

In a small team, tribal knowledge is efficient. Everyone knows everyone, context is shared through proximity and daily conversation, and the overhead of formal documentation would actually slow things down more than it helps. The tribe is small enough that the knowledge circulates naturally.

The problem is that tribal knowledge doesn't scale, and the point at which it stops scaling usually arrives before the team notices.

The scaling break

The break typically happens between ten and twenty engineers. Below ten, most engineers have a reasonable mental model of the whole system and know who to ask about any given component. Above twenty, the system has grown beyond any individual's comprehension, the team includes people who've joined recently enough that they don't have the historical context, and the engineers who do hold the tribal knowledge are increasingly stretched between their own work and the growing burden of answering questions.

The symptoms are recognisable: meetings that exist primarily to share context rather than make decisions. Slack threads where half the discussion is reconstructing the background before the actual question can be addressed. Onboarding that takes months because the new hire has to absorb context through osmosis rather than reading. Decisions that get relitigated because nobody remembers (or the current team never knew) that the same question was discussed and resolved six months ago.

Each of these symptoms has a cost, and the costs add up to something much larger than most teams recognise because each individual instance seems minor.

Why it blocks async work

Tribal knowledge is fundamentally incompatible with asynchronous work. When the context needed to make a decision lives in someone's head, the decision can only happen when that person is available to share it. This forces everything into synchronous channels: meetings, real-time Slack conversations, shoulder-taps.

In a distributed or hybrid team, the incompatibility is even more acute. The engineer in a different timezone who needs context about the payments system has to wait until the engineer who holds that context is online. The decision that could have been made asynchronously from a doc instead blocks on a calendar slot.

Converting tribal knowledge into searchable documentation unlocks async decision-making because the context is available to anyone, at any time, without requiring the knowledge holder to be present. An engineer who can read the decision log for why the payments system is structured the way it is doesn't need to schedule a meeting to find out.

The conversion problem

The challenge of converting tribal knowledge into documentation is that the people who hold it are typically the busiest people on the team: the senior engineers and early employees whose time is most valuable and most oversubscribed. Asking them to sit down and write out everything they know is asking them to take on a large, unbounded task on top of their existing work.

Self-writing documentation addresses this by capturing tribal knowledge from the channels where it's already being shared. When a senior engineer explains a design decision in Slack, that explanation is captured and structured. When a meeting covers the history behind a system's current architecture, the discussion becomes part of the documentation. When a PR description explains why a particular approach was chosen, the reasoning is preserved alongside the code.

The senior engineer doesn't write docs. They do their normal work, and the docs emerge from it.

Frequently asked questions

How do we identify our tribal knowledge? Look for questions that get asked repeatedly and can only be answered by specific people. Look for Slack threads where the first several messages are establishing context before the actual question. Look for meetings that exist to share information rather than make decisions. These are all symptoms of knowledge that should be documented but isn't.

What's the most valuable tribal knowledge to capture first? System architecture decisions (why things are built the way they are), incident history (what went wrong and what was changed as a result), and integration boundaries (how different services communicate and why). These are the areas where missing context causes the most expensive mistakes.

Can tribal knowledge be fully eliminated? No, and it shouldn't be. Some knowledge is inherently contextual and develops through experience in ways that documentation can't fully capture. The goal is to reduce the proportion of critical operational knowledge that exists only in people's heads, not to eliminate informal knowledge transfer entirely.

Related reading: The bus factor, Documentation debt, Why engineering docs matter. Related pages: Self-writing docs, Knowledge retention, For engineering teams.