Sharing Knowledge Asynchronously: Code Review, ADRs and Docs-as-Code

Code review, ADRs, docs-as-code, runbooks, postmortems: the ways of sharing knowledge that need neither the same place nor the same moment, and that produce a lasting trace — provided you go about it the right way.

In the guide to collaboration modes, we set out a rule: explicit knowledge travels asynchronously. Where synchronous modes pass on intuition through contact, asynchronous modes capture what can be written down — and produce a trace that survives departures. But you still have to avoid the classic trap: documentation that no one reads and no one keeps up to date. This article details the practices that work, and why.

I. The strength and the limit of writing  

Writing has an advantage no synchronous mode matches: it depends on no one. It can be read at three in the morning during an incident, six months after its author has left, by someone who wasn’t there when the decision was made. It’s the bedrock of a team’s memory.

But writing has two enemies. The first is decay: documentation that doesn’t follow the code becomes a trap, because a reader can’t tell what’s still current from what isn’t. The second is the illusion of completeness: believing a document captures an expertise, when it only fixes the explicit part of it.

Hence the thread of this article: the good asynchronous modes are those that fight decay — by bringing the writing close to the code, keeping it alive, and documenting the why rather than the how.

II. Code review: transferring without a meeting  

Code review is the most frequent transfer mode — and the most wasted. Too often it shrinks to a checkbox: “it compiles, the tests pass, I approve.” You validate the what, and lose the why.

Yet a well-run review is a powerful transfer channel:

• For the author, explaining their intent in the pull request description forces them to clarify their thinking.
• For the reviewer, reading code you didn’t write is the most regular way to discover areas of the system you never touch.
• For the team, review discussions spread the conventions, the known traps, the architectural preferences.

A few principles so it actually transfers:

• Comment the why, not just the what. “Rename this variable” transfers little; “rename it, because data hides the fact that it’s already filtered” transfers a rule.
• Ask questions rather than give orders. “Why this choice?” opens a conversation; “change this” closes it.
• Spread the reviewers. If the same person always reviews a domain, you recreate a bottleneck — and a disguised bus factor of 1.
• Keep reviews small. You seriously review 50 lines; you skim 800. A big pull request transfers nothing.

III. ADRs: documenting the why  

This is the centerpiece of asynchronous transfer, and the most neglected. An ADR (Architecture Decision Record) is a short record that captures an architecture decision at the moment it’s made.

Code says what the system does. It never says why you chose this database, ruled out that library, or tolerated that workaround. That reasoning lives only in the heads of those who were there — and disappears with them. This is exactly Chesterton’s fence: without the why, a successor doesn’t know whether they can tear the fence down.

An ADR fits on one page and follows a simple format:

• Context: what problem, what constraints at the time of the choice?
• Decision: what was decided, stated clearly.
• Alternatives ruled out: what you considered and why you rejected it — often the most valuable part.
• Consequences: what the decision implies, including its accepted downsides.

Two rules make all the difference:

• Write the ADR at the moment of the decision, not months later, when the context has already evaporated.
• Never rewrite history. An ADR is immutable: if a decision changes, you write a new one that supersedes the old (“superseded by ADR-012”). The chain of decisions tells the story of the system’s evolution — it’s a memory, not a state.

Stored in the repository, next to the code, ADRs form the logbook every newcomer should be able to read to understand how we got here.

IV. Docs-as-code: bringing the docs close to the code  

The worst enemy of documentation is the distance separating it from the code. A wiki hosted elsewhere, edited separately, reviewed by no one: it decays in silence, and every stale piece of information undermines trust in all the rest.

The docs-as-code approach flips the problem by treating documentation like code:

• it lives in the repository, in Markdown, next to what it describes;
• it is versioned: you see who changed what, and when;
• it goes through review: a code change that makes the docs wrong is fixed in the same pull request;
• it can be tested: dead links, code examples that no longer compile, and so on.

The benefit is twofold. The docs stay up to date because they’re updated in the same place and at the same time as the code. And they gain credibility: a reader can trust a document they can see was touched at the same time as the code it describes.

Good documentation isn’t the documentation that’s complete, it’s the one you can trust. Proximity to the code is what creates that trust.

V. Runbooks: operational memory  

A runbook is a written, tested incident procedure, accessible to everyone: how to restart this service, restore this database, respond to this alert. It’s the asynchronous translation of knowledge that, otherwise, a single expert holds — and that you discover is missing in the middle of an outage.

A good runbook:

• starts from a symptom (“alert X fires”) and leads to concrete actions;
• is tested outside of incidents — a runbook never tried is a reassuring fiction;
• is dated and reviewed, because a stale procedure is more dangerous than no procedure at all.

Its most precious effect: it turns panic into sure-footed steps, and makes on-call practicable by someone other than the system’s author.

VI. Blameless postmortems: learning from incidents  

Every incident is knowledge waiting to be captured — provided you don’t look for someone to blame. The blameless postmortem starts from a principle: people act as best they can with the information they have; if a mistake was possible, it’s the system that needs fixing, not the person.

A useful postmortem describes what happened, why the system allowed it, and what durable safeguards follow from it. Published and archived, it becomes a collective memory: the next person facing the same symptom won’t have to relearn it the hard way.

Without blame, people tell the truth — and it’s the truth you learn from. With blame, they protect themselves, and the knowledge is lost.

VII. How to combine them  

These modes don’t compete, they form a chain:

• a decision is recorded in an ADR;
• its implementation goes through a code review that spreads the details;
• how it works is documented in docs-as-code, next to the code;
• its operation is equipped with a runbook;
• and when something breaks, a postmortem closes the loop by producing new knowledge.

What the whole chain has in common: bringing the writing close to what it describes, documenting the why, and keeping each trace alive. That’s what separates documentation that transfers from documentation that lies.

Conclusion  

Asynchronous modes don’t replace contact — they capture what contact can’t make permanent. Their value isn’t in the volume produced, but in the trust you can place in them: an ADR at the right moment, a review that explains, docs glued to the code, a tested runbook are worth a thousand forgotten wiki pages.

Remember this: it isn’t writing more that protects a team, it’s writing what lasts, close to the code, and keeping it alive. That’s the writing that will still speak when its author is gone.

Useful links  

• Documenting Architecture Decisions — Michael Nygard
  The founding article on ADRs: format, motivation, and examples for documenting the why behind a decision.

• adr.github.io — Architecture Decision Records
  The reference portal on ADRs: ready-to-use templates, tools, and format variants.

• Google SRE Book — Postmortem Culture
  The reference chapter on blameless postmortems: principles, pitfalls, and concrete examples.

• Write the Docs — Docs as Code
  An introduction to the docs-as-code approach: tools, workflow, and the benefits of treating documentation like code.