Knowledge Sharing
Code review, documentation, pairing, design review and postmortems each spread a different kind of knowledge at a different cost. Choosing between them starts with naming which kind is missing.
The requirement, the obvious build, and why it breaks
Every lesson starts where the work starts: someone asked for something, and the first implementation that comes to mind survives until the requirement changes.
Which knowledge is failing to spread here, and which mechanism actually spreads that kind?
A team keeps rediscovering the same things: the same bug pattern in three services, the same argument about error handling every quarter, and a new joiner who takes four months to become productive.
We should document more. Set up a wiki, ask everyone to write up what they know, and new people can read it.
It picks one mechanism for every kind of gap. A wiki is a good answer for orientation and a bad answer for judgement, and most teams' actual gap is judgement.
- It picks one mechanism for every kind of gap. A wiki is a good answer for orientation and a bad answer for judgement, and most teams' actual gap is judgement.
- Written documentation decays fastest exactly where change is fastest, so the pages about the parts that most need explaining are the ones most likely to be wrong (Documentation Decay).
- It has no consumer. Pages written speculatively, in case someone needs them, are read by nobody and maintained by nobody — and their existence discourages asking.
- It also misdiagnoses the four-month ramp. New joiners are usually slowed by not knowing *how decisions get made here* and *what is load-bearing*, neither of which is documentable in the form a wiki takes.
- Meanwhile the mechanisms that do work — review, pairing, postmortems — already exist and are usually being run in a way that spreads nothing (What Code Review Is For).
What limits the solution, and what must never stop being true
This domain leads with these two. A design that ignores its constraints is not a design, and an invariant nobody named is one nothing is protecting.
- Every mechanism costs the time of the people who already know, which is the scarcest resource on the team.
- Nothing written will be maintained unless it is next to the thing it describes and someone reads it regularly (Documentation Decay).
- People will not attend a ceremony that does not visibly change an outcome, and attendance cannot be mandated into value.
- Every mechanism adopted must have an identifiable output that someone consumes. A practice with no consumer is a cost with no return.
- The reasoning behind decisions that constrain future work must end up in the repository, not in a meeting (Decision Records).
Who owns what, and where the seams fall
Responsibilities decide boundaries; boundaries decide what an interface has to say.
- Each mechanism owns one kind of knowledge, and the team owns knowing which kind it is short of.
- Whoever runs a mechanism owns its output: a review owns the comments that change the design, a postmortem owns the action items, a design review owns a decision record (Architecture Decision Records).
- The team owns pruning. A practice with no consumer should be stopped, and stopping one is what makes room for the one that would help (The Complexity Budget).
- The useful boundary is between knowledge that can be written and knowledge that can only be practised. Written mechanisms are cheap and cover the first; only pairing, review and shared incidents cover the second.
- A second boundary is push versus pull. Documentation is pull — it works when someone knows to look. Review and pairing are push — they reach people who did not know they needed it (Review as Design Feedback — and Why It Arrives Too Late).
- Anything that must be true across the codebase is better expressed as a lint rule or a test than as shared knowledge, because a mechanism that requires everyone to remember will fail as the team grows (What to Automate Out of Review).
Five mechanisms, five different jobs
These are usually discussed as a bundle of good practices, which hides the useful fact: they do not overlap much. Each is strong on one kind of knowledge and weak on the others, and a team can be doing three of them well and still have a glaring gap.
The cost column matters as much as the fit column, because all five spend the same scarce resource — the attention of people who already know things.
- Only pairing and postmortems reliably transfer judgement, and both are expensive or infrequent — which is why judgement is the kind of knowledge teams are most short of.
- Only documentation persists past everyone leaving, which is why it remains worth writing even though it is the weakest transfer mechanism while people are present.
- Review is the highest-leverage of the five for most teams, because it is already happening and the change required is to what gets discussed rather than to anyone's calendar.
| Mechanism | Spreads best | Costs | Fails by |
|---|---|---|---|
| Code review | How we do things here; local conventions; how to change *this* code safely | Reviewer time per change; latency | Becoming a correctness-and-style check, which spreads nothing (What Code Review Is For) |
| Documentation | Orientation, setup, why a non-obvious decision was made | Cheap to write, expensive to keep true | Decaying silently, then being believed (Documentation Decay) |
| Pairing | Judgement and tacit skill — the kind nothing else transfers | Two people, one output. The most expensive by far | Being mandated as a percentage, or becoming one person watching another |
| Design review | Why a boundary is where it is, while it can still move | An hour of several senior people, before implementation | Happening after the code exists, when nothing can change (Design Review) |
| Postmortems | How the system fails in reality, which no document predicts | A few hours after an incident, plus follow-through | Producing action items nobody schedules — DevOps owns the depth on learning from incidents |
Diagnose the gap, then pick the mechanism
The failure that produces two hundred unread wiki pages is not laziness; it is a diagnosis skipped. Different symptoms point at different missing mechanisms, and several of them are not knowledge problems at all.
Two of the options below are worth noticing because the correct response is a code change rather than a practice: a recurring defect wants a check, and a recurring argument wants a written decision.
Which kind of knowledge is failing to spread, and is a practice even the right instrument?
when A pattern nobody knew was dangerous, repeated independently.
cost Not a knowledge gap. Make it a lint rule, a type or a shared module, so nobody has to know. The cost is that the check will occasionally block a legitimate case (What to Automate Out of Review).
when Error handling, folder layout, when to use a queue — relitigated by whoever is newest.
cost A missing decision, not missing knowledge. Write it down with a revisit trigger. Cost: the decision may be wrong and is now harder to change (Decision Records).
when They can read the code but cannot judge what is safe to change.
cost Pairing on real work plus review that discusses design. Genuinely expensive in senior time, and the only thing that works for judgement.
when Nobody else can evaluate changes there.
cost A bus factor problem wearing a knowledge-sharing costume; transfer through a real change rather than a document (Bus Factor).
when Onboarding stalls on environment and tooling.
cost The cheapest gap there is, and the one documentation is actually good at. Write the README, keep it in the repository, and have the next joiner fix it as their first pull request.
when The system fails the same way twice.
cost Postmortems exist but the action items are not scheduled. This is a planning failure, and adding another mechanism will not touch it; the postmortem practice itself is DevOps' subject.
How each mechanism fails while appearing to work
Every one of these has a degenerate form that is indistinguishable from the real thing on any dashboard: reviews are happening, pages exist, postmortems are filed. The degenerate forms are the normal state, not the exception, and they are what teams are usually defending when they say they already do this.
The response column is deliberately small in every row. These are not new practices; they are adjustments to practices already running.
| Trigger | Symptom | Cause | Response |
|---|---|---|---|
| Reviews are fast and approvals are high | Comments are about naming and formatting; no design question has been asked in months | The review is checking the diff rather than the design, which is what a linter is for | Ask one design question per review: what would the next requirement do to this? It costs a minute and changes what transfers (Review as Design Feedback — and Why It Arrives Too Late). |
| A documentation drive is completed | Two hundred pages, four of which are ever opened | Written speculatively, with no consumer and no proximity to the code | Write only in response to a real question, and write it next to the code the question was about (Docs Close to Code). |
| Pairing is measured as a percentage of time | Two people at one screen, one of them reading email | A high-bandwidth practice converted into a compliance metric | Pair on specific hard things — the unfamiliar area, the risky change — and stop measuring the hours. |
| Design reviews are scheduled | They happen after implementation and produce cosmetic comments | Held at a point where the boundary can no longer move | Move it before the first line of code. That single change is most of the value (Design Review). |
| Postmortems are written up thoroughly | The same incident recurs with a better-documented history | Action items are recorded but never enter anyone's plan | Cap action items at three and assign each to a named person with a date. Unscheduled items are notes, not actions. |
How to build it
Most important first.
- Name the gap before choosing the mechanism. "The same bug in three services" is a different gap from "the same argument every quarter", and they need different responses.
- Prefer mechanisms that ride on work that is happening anyway. Review, pairing and postmortems have a near-zero adoption cost because they are already scheduled; a new ceremony is a new cost (Review Size).
- Put the durable outputs in the repository, next to the code: decision records, a comment at the constant, a README in the module. Anything stored elsewhere is on a decay clock (Docs Close to Code).
- Convert repeated arguments into written decisions with revisit triggers. The quarterly error-handling argument is not a knowledge gap, it is an undocumented decision (Revisit Triggers).
- Convert repeated bugs into checks. The same defect in three services is a lint rule, a type, or a shared module — not a training problem (Duplicate Knowledge).
- Measure the mechanism by its consumer. If nobody can name who read the last five pages written, stop writing pages and put the effort into review.
What the next change costs
The field this whole domain exists for. A structure is only better if it makes the change after this one cheaper — and it is worth saying which changes it does not help.
- A team that spreads knowledge well pays continuously — review time, pairing time, records to write — and the return is that the next change in an unfamiliar area costs one person's time rather than one specific person's time.
- A team that does not pays in ramp-up: four months per new joiner, repeated per hire, plus one archaeology project per departure (Bus Factor).
- The cheapest single intervention is usually turning existing code review from a correctness check into a design conversation. It costs nothing new and changes what is transferred (Review as Design Feedback — and Why It Arrives Too Late).
- The most expensive intervention with the worst return is a documentation project commissioned separately from the work, and it is the one most often chosen because it is the only one that looks like progress.
- Every mechanism spends senior time, which is the constraint on both spreading knowledge and shipping. There is no version of this that is free, and teams that claim otherwise are running the mechanism perfunctorily.
- Pairing transfers the most and costs the most: two people, one output, and it is genuinely slower on the day.
- Written records are cheap to produce and expensive to keep true, and a confidently wrong record costs more than no record (Documentation Decay).
What can go wrong
- A documentation initiative produces two hundred pages, of which four are read, and the rest are found two years later contradicting the code.
- Code review becomes formatting comments and approvals, spreading nothing, while everyone reports that the team does code review (What Code Review Is For).
- A postmortem process produces action items that nobody schedules, so the same incident recurs with a better-documented history.
- Pairing is mandated as a percentage, which converts a high-value practice into a compliance metric and produces two people watching one person work.
- The team adopts every mechanism at once, each one gets a fraction of the attention it needs, and the conclusion drawn is that none of them work.
- Every mechanism depends on the time of experienced people, and they are the same people every mechanism depends on. Adopting three at once is how all three become perfunctory.
- Written outputs depend on being close to the code to survive; anything in a separate system depends on somebody remembering it exists (Documentation Decay).
- Pairing and review depend on psychological safety in a way documents do not: a review culture where objections are costly transfers nothing except caution (Tone, Disagreement and Receiving Review).
- "More documentation is always good." Documentation with no reader is pure cost with a maintenance tail, and its presence discourages the question that would have got a correct answer (Comments).
- "Pairing is the best mechanism." It is the highest-bandwidth and the most expensive, which makes it right for the hardest knowledge and wasteful for the rest. Using it for onboarding to a well-tested CRUD service is spending the most on the cheapest gap.
- "Knowledge sharing is a culture problem." Some of it is. Much of it is a mechanism problem with a mechanical fix: the recurring argument needs a written decision, and the recurring bug needs a check (What to Automate Out of Review).
- "We do code review, so knowledge spreads." Only if reviews discuss design. A review that checks correctness and style transfers almost nothing, and it is the most common form of review there is (A Review Checklist Worth Reading).
Testing it, and how it ages
- The ramp-up test: how long until a new joiner ships a change to an unfamiliar area unaided? It is the only end-to-end measure of whether any of this is working.
- The consumer test, per mechanism: name the last person who used its output. A mechanism that fails this is a cost.
- The recurrence test: is the same argument or the same defect appearing again? Recurrence is the signal that a decision or a check is missing, not that people need reminding.
- What works changes with team size. Under about eight people, everything works by conversation and formal mechanisms are overhead; the transition to needing written decisions is usually felt as "we keep having the same argument".
- Documentation value inverts over time: early on it is waste because everything changes, and later it is essential because the authors have left. Teams typically start writing about one year after it would have been useful.
- Mechanisms decay into ceremony unless someone periodically asks what they produced. The decay is not a sign the mechanism was wrong; it is the default state of anything recurring (Revisit Triggers).
Where this applies
This domain's advice is contested more than most. These labels say what each claim is specific to — and where CONTESTED appears, the note gives the strongest form of the opposing view rather than a caricature.
- SCALE-SPECIFICBelow roughly eight engineers in one room, knowledge shares itself: everyone hears every decision, and formal mechanisms are overhead that buys nothing. The first real transition is felt as "we keep having the same argument", and the answer at that point is written decisions, not a wiki. The second transition, somewhere past fifty, is that no mechanism reaches everyone and the answer shifts to encoding knowledge in tooling — templates, lint rules, golden paths — because a practice that depends on everyone remembering does not survive that size. Importing the large-organisation answer early gives a small team a platform nobody needs; importing the small-team answer late gives a large one a culture of tribal knowledge.
- CONTESTEDThe strongest opposing view holds that documentation is nearly worthless in a changing codebase and that all durable knowledge should live in code, tests and types — "the code is the documentation", stated by people who mean it seriously and back it with executable examples and characterization suites rather than prose. They are right that prose decays and that a wrong document is worse than none. The counter is that code cannot express *why*: no test records that the retry window matches a provider's deduplication window, and that class of knowledge is exactly what departures destroy.
- CONTESTEDOn pairing specifically the profession genuinely disagrees. The strongest case for it: it is the only mechanism that transfers judgement in real time, catches design problems before they are written, and reliably halves ramp-up. The strongest case against: it doubles the cost of every task for a benefit that is hard to observe, exhausts people who think better alone, and is frequently mandated as a percentage, which converts it into theatre. Both camps contain excellent teams, which should make anyone suspicious of a policy either way.
Where the depth lives
This domain teaches the codebase-level structure and hands the rest off.
- — Testing & Reliability Engineering — a characterization suite is a knowledge-sharing mechanism disguised as a test suite: it encodes what the system actually does in a form that survives every author, which is something no document manages.