What Code Comments Cannot Carry: The Documentation Transfer Problem in Open Infrastructure

The Illusion of a Well-Documented Project

There is a common assumption in open infrastructure communities that a thoroughly commented codebase is a well-documented project. It is a reasonable assumption on its surface. Comments explain what functions do. README files describe installation steps. Wikis catalog configuration options. By most conventional measures, the project appears ready for handoff.

Then a maintainer leaves—and the team discovers that none of that documentation explains why the authentication module was restructured in the spring of 2021, or why a seemingly obvious optimization was deliberately avoided three years ago after it caused a cascade failure in a staging environment that no longer exists. The code is present. The reasoning is gone.

This is the documentation transfer problem, and it is one of the most consequential and least-discussed failure modes in open infrastructure today.

Tacit Knowledge and the Limits of Written Record

Cognitive scientists distinguish between explicit knowledge—information that can be articulated and recorded—and tacit knowledge, which is held in practice, judgment, and accumulated experience. A maintainer who has worked on a platform for four years carries an enormous reservoir of tacit knowledge: which edge cases reliably surface under high load, which contributors tend to introduce regressions in specific subsystems, which architectural constraints were imposed by a funding requirement that has since expired.

None of that knowledge lives in a pull request. Very little of it survives a transition if it has not been deliberately externalized before the maintainer's departure.

The challenge is not simply one of effort or discipline. Even motivated maintainers often struggle to articulate what they know, precisely because tacit knowledge feels self-evident to those who hold it. The things that seem most obvious to an experienced maintainer are frequently the things that never get written down—because why would anyone document something so apparent?

The answer, of course, is that it is only apparent to the person who already knows it.

Architecture Decision Records as Institutional Memory

One of the most effective tools that mature open infrastructure projects have adopted is the architecture decision record, or ADR. An ADR is a short, structured document that captures not just what architectural decision was made, but the context that surrounded it, the options that were considered, the tradeoffs that were evaluated, and the conditions under which the decision should be revisited.

What distinguishes a living ADR practice from a one-time documentation effort is the discipline of treating every significant architectural choice as a decision worth recording at the moment it is made—not retrospectively, when context has already faded. Projects that maintain this discipline consistently report that new contributors are able to understand the reasoning behind unfamiliar design choices far more quickly than in projects that rely on comment threads or informal Slack conversations.

The ADR format also has a useful secondary effect: it forces the decision-making process itself to become more explicit. When maintainers know they will need to articulate their reasoning in a structured record, they tend to think more rigorously about the tradeoffs they are navigating.

Video Walkthroughs and the Spoken Layer of Documentation

Written documentation has inherent limitations. It captures what a maintainer knows how to express in prose, which is not always the same as what they know how to do. Some operational knowledge—the sequence of steps a maintainer follows when a particular alert fires at 2 a.m., the judgment calls embedded in a deployment process, the way a complex subsystem behaves under conditions that are difficult to reproduce—is more naturally conveyed through demonstration than description.

A growing number of open infrastructure projects have begun supplementing written documentation with recorded video walkthroughs. These are not polished tutorial productions; they are informal screen recordings in which a maintainer narrates their reasoning as they navigate a system, investigate a problem, or execute a procedure. The production cost is low. The informational value is high.

The key is to record these walkthroughs while the knowledge is still fresh and the maintainer is still available to answer follow-up questions. Projects that wait until a transition is imminent often find that the departing maintainer's attention is already divided and the resulting recordings are rushed and incomplete.

Structured Onboarding as a Documentation Audit

One of the most reliable ways to identify gaps in institutional documentation is to run a new contributor through a structured onboarding curriculum and observe where they get stuck. Every point of confusion is a signal that something the experienced team takes for granted has not been adequately externalized.

Effective open infrastructure projects treat onboarding not as a one-time orientation but as a continuous feedback mechanism. When a new contributor asks a question that cannot be answered by pointing to existing documentation, the answer to that question—once given—should be added to the documentation before the next contributor arrives. Over time, this practice produces a documentation base that reflects actual confusion points rather than the idealized mental model of the original maintainers.

This approach also distributes the documentation burden across the contributor community rather than concentrating it on a single maintainer who may already be stretched thin.

The Pre-Departure Protocol

Even projects with strong ongoing documentation practices benefit from a structured pre-departure protocol when a core maintainer announces their intention to leave. This is not a last-minute scramble; it is a deliberate process that begins as early as possible after the departure is known.

A well-designed pre-departure protocol typically includes a series of structured interviews in which the departing maintainer is guided through specific questions about the systems they own: What would you want your successor to know that is not currently written down? What are the failure modes you watch for that others might miss? What decisions might look wrong from the outside but are correct given context that isn't visible in the code?

The output of these interviews should be reviewed, organized, and incorporated into the project's permanent documentation before the maintainer's last day. Projects that treat this process as optional routinely discover, months later, that critical operational knowledge has been lost.

Documentation as Infrastructure

The deeper shift that distinguishes projects with durable documentation cultures from those that perpetually struggle with knowledge loss is conceptual. Documentation must be understood as infrastructure—not as a supplement to the work, but as a core component of the system itself.

This framing has practical consequences. Infrastructure requires ongoing maintenance. It requires investment even when no immediate crisis demands it. It requires the same kind of deliberate design that governs the technical systems it describes. Projects that treat documentation as an afterthought will always find themselves in crisis when a maintainer departs. Projects that treat it as infrastructure will find that transitions, while never frictionless, rarely become catastrophic.

The knowledge that makes an open infrastructure project function is a commons. Protecting that commons requires the same intentionality that protects every other shared resource the project depends on.