Why “just write more docs” can't capture how your team actually operates — and what to do instead.
At 3 a.m. the dashboards all go red, and the runbook is useless.
It's a good runbook. Someone wrote it carefully, it has the right commands, it even has a flowchart. But the failure isn't in the flowchart. The on-call engineer stares for a moment, then types something the runbook never mentions: rolls back one specific config flag, restarts the followers but not the leader, waits ninety seconds before re-enabling traffic. Green. Afterward someone asks how they knew, and the honest answer is a shrug: “It had the same shape as that thing in March. You just learn the smell.”
Where did that knowledge live? Not in the wiki. It wasn't under-documented; it was never the kind of thing a document can hold. And if that engineer leaves, it walks out the door with them, no matter how many pages anyone writes.
Every engineering org runs on two kinds of knowledge and only manages one of them. The other one we keep promising to “write up someday,” as if it were merely undocumented. It isn't. It's a different substance entirely, and the most useful map of it comes not from software but from a performance scholar studying how cultures remember.
In 2003, Diana Taylor published The Archive and the Repertoire: Performing Cultural Memory in the Americas (Duke University Press), and her central distinction has quietly explained more about engineering teams than most engineering books. She split cultural memory into two systems.
The archive is the enduring, recorded stuff: “written texts, relics, recordings,” artifacts that persist, that you can store and catalog and consult, that sit still while you study them. The repertoire is everything transmitted by doing: “scenarios and performed behaviors... conveyed in gestures, the spoken word, movement, dance, song, and other performances.” The repertoire is knowledge that exists only in the act, in someone performing it, present, in real time.
Taylor's load-bearing claim, the one that matters for your on-call rotation, is that the repertoire is not a weaker archive waiting to be written down. It is a different mode of knowledge, one the archive structurally cannot hold. She argues Western culture is logocentric: it trusts the written so reflexively that it treats embodied knowledge as illegitimate, or at best as raw material that becomes “real” knowledge only once transcribed. That bias, she says, makes us blind to an entire register of how humans actually know things.
Her examples are not from a server room, and that's the point of their power. The HIJOS, the children of the disappeared in Argentina, carry the memory of state atrocity through escraches: embodied public demonstrations performed at the homes of unpunished perpetrators. That knowledge was deliberately kept out of every official archive; it survives because it is performed, body to body, generation to generation. A dance is not a weak version of a paragraph about a dance. The content is in the doing, and the doing is the only place it fully exists.
Hold that sentence next to your team's tacit operational knowledge and it stops being a humanities abstraction.
The reason the repertoire resists the archive isn't sloth or bad tooling. It's epistemology, and the canonical statement of it predates Taylor by nearly forty years.
In The Tacit Dimension (1966), the chemist-turned-philosopher Michael Polanyi gave us the line the whole subject rests on: “we can know more than we can tell.” His example is the one everybody has lived: you can ride a bicycle, and you cannot write down how. You could fill pages about countersteering and angular momentum, hand them to someone who has never ridden, and watch them fall over. The knowledge is real, it is precise, it is yours, and it is constitutively inarticulable. It lives below the level where words reach.
This is the mechanism under Taylor's claim, and it is exactly why “just write more docs” fails as a category, not as an effort. Nobody learns on-call by reading the on-call doc, for the same reason nobody learns to ride a bike from a manual. The feel for when a deploy smells wrong, the instinct that this alert is noise but that one means drop everything, the muscle memory of an incident commander who has run forty incidents: these are tacit. They are not absent from the wiki because someone was lazy. They are absent from the wiki because the wiki is the wrong kind of container, the way a bottle is the wrong container for a song.
Even the management science that most wants to “convert” tacit knowledge into explicit form concedes this. Ikujiro Nonaka's well-known SECI model describes how tacit knowledge can become explicit, but its first and load-bearing step is socialization, person-to-person, by shared experience. The leading theory of writing-it-down says the writing-down only works as the back half of a social, embodied process. There is no solo path. The document is downstream of the apprenticeship, never a substitute for it.
Here is the part that should make every engineer sit up: a computer scientist made Taylor's exact argument, about software, eighteen years before her book, and most of our field has spent forty years not listening to him.
In 1985, Peter Naur, the N in BNF and a Turing Award winner, published “Programming as Theory Building.” Its thesis is blunt and, on first contact, slightly heretical: a program is not its source code. A program, Naur argued, is a theory: a shared mental model, living in the heads of the people who built it, of how the problem maps to the solution, why the code is shaped the way it is, what the world looks like such that this is the right design. The source code and the documentation are residue of that theory, not the theory itself.
And then the line that lands like a verdict on every knowledge-base initiative ever funded: a program dies when the people who hold its theory disperse. Not the executable (“the running executable after such a death remains operational”) but the program as a living thing you can safely change. Hand a perfectly compiling, well-documented codebase to a fresh team and ask them to evolve it, and they will move slowly, fearfully, and wrongly, because the theory (the why, the smell, the load-bearing intuitions about what will break) left with the original minds. The artifact persists; the knowledge is gone. The archive remained intact and the repertoire walked out the door.
That is Taylor's distinction, stated in 1985, in our own vocabulary, by one of our own. The repertoire even has an industry name we use without noticing what we're admitting: tribal knowledge, which the field itself acknowledges “has a lot of commonality with tacit knowledge,” and that it is “stored in members' heads, hard to codify.” Its risk has a name too: the bus factor, the count of people who'd have to vanish before a system becomes unmaintainable. The bus factor is just Taylor's “when the people leave, the repertoire leaves with them,” wearing an ops hat. By the softer industry estimates the imbalance is severe: one frequently-cited knowledge-management figure puts tacit knowledge at something like 80% of an organization's total, with another claiming a large share of institutional knowledge sits with single individuals. Treat the exact numbers as the loose marketing estimates they are, but the direction is the lived experience of everyone who has watched a senior engineer give two weeks' notice and felt the floor tilt. The expensive part was never in the repo.
So here is the mistake nearly every team makes, now visible for what it is: the documentation push, the quarterly “let's finally write everything down,” is an attempt to transcribe a dance into a paragraph. It is not under-ambitious; it is miscategorized. It pours real effort into moving knowledge from the repertoire into the archive across a boundary that, for the tacit core, does not have a door.
And it has a failure mode worse than wasted effort, the subtle one worth naming clearly. Writing more docs can make you less safe, by manufacturing the illusion of capture. The wiki exists; the runbook is thorough; the onboarding doc is forty pages, so the org believes the repertoire is preserved. The bus factor feels addressed. Then the one person who actually held the theory leaves, and the team discovers the forty pages describe the archive of the system and contain nothing of its repertoire. This is Taylor's logocentrism turned into operational risk: we trust the knowledge because it is written, and the writtenness is precisely what lulls us. A confident archive is more dangerous than an honest gap, because the gap, at least, you can see.
One distinction keeps this honest, because a related idea gets conflated with it. Jeffrey Pfeffer and Robert Sutton's The Knowing-Doing Gap (2000) diagnoses organizations that know what to do and fail to act, with talk substituting for action. That is a real and different problem. The archive/repertoire claim is sharper: some operational knowledge was never knowable in the archive's mode at all. The knowing-doing gap says you had the knowledge and didn't use it. Taylor and Naur say the most valuable knowledge was never the kind you could file. Don't reach for “we just need better documentation discipline,” that's the knowing-doing frame, and it will send you to write more of exactly the thing that can't help.
None of this is an argument against documentation, and getting that wrong inverts the whole point. The discipline cuts both ways. The archive is the right container for archive-shaped knowledge: API contracts, config references, the sequence of commands, the decisions and their rationale. Write those well; an Architecture Decision Record that captures why you chose eventual consistency is genuinely valuable and genuinely archivable. The error is not writing docs; the error is using docs for the repertoire, and, just as wastefully, not writing the archive because “nobody reads docs anyway.” Put each kind of knowledge in its proper container. The skill is telling which is which: an ADR can hold the decision; only a person, performing, can transmit the feel for when a deploy smells wrong.
For the repertoire, you transmit it the way every culture in human history has transmitted a repertoire: by doing it, together, in real time. Taylor calls performances “acts of transfer,” and the striking thing is that the best engineering orgs already do this; they just don't know they've been doing performance studies.
Consider the vocabulary the chaos-engineering field reached for, entirely on its own, to describe game days: staged production incidents run as fire drills. Read their own literature and one phrase recurs, unprompted, everywhere: teams run game days “so teams build muscle memory, so people aren't running around with their hair on fire when something bad happens.” Muscle memory, an embodied-knowledge term, is what the discipline independently decided it was building. That is the repertoire by another name: knowledge installed in people's hands and reflexes by performing the incident before the incident is real. Game days also test “human response processes,” not just systems, and explicitly aim to distribute the knowledge, to “identify subject matter experts” and spread expertise “so it doesn't bottleneck within a handful of people.” That is a direct, performed answer to the bus factor, achieved without writing a single page, because the thing being transferred was never page-shaped.
The same logic names the rest of the toolkit, and explains why each works. Pairing and mobbing transmit the smell in the doing: the senior says “wait, don't deploy on a Friday into that service, here's what happens,” and the junior absorbs a piece of theory no ADR could carry. Shadowing an on-call rotation is apprenticeship: you sit beside the expert through real pages and learn the reflexes by proximity, exactly as a craft is learned. Incident reviews run as teaching, where “why did you do that?” is a learning question, not an indictment, pass the theory forward. Notice that every one of these is synchronous, social, and embodied. None of them is a document, because Polanyi's bicycle cannot be a document.
The practical shift is small and changes everything. When a piece of operational knowledge worries you, the instinct is to ask: “Why isn't this documented?” It's the wrong question, and it sends you to build more archive against a repertoire problem.
Ask two better questions. First: is this knowledge archive-shaped or repertoire-shaped? If it's a decision, a contract, a procedure, write it, and write it well; that's archive, and the archive is good at it. If it's a feel, a smell, a reflex, a theory of why the system is the way it is, stop trying to write it, and ask the second question: who is this knowledge being performed with, and who's next in the apprenticeship? Who is pairing with the person who holds it? Whose hands are on the controls during the next game day? When the engineer who knows the 3 a.m. fix gives notice, the recovery plan is not “have them write it all down in their last two weeks.” It is “have them run incidents beside their successor for those two weeks,” because the knowledge moves the only way it can: person to person, in the act.
Naur told us in 1985 that the program lives in the programmers and dies when they disperse. Taylor told us in 2003 that the repertoire is a different kind of memory the archive can never hold. They were describing the same truth from two ends of the university, and your team lives it every on-call shift. The archive is real and worth keeping. But it is the visible, written, comfortable fraction of what your team knows, and the part that saves you at 3 a.m. was never in it, and never could be. Stop trying to write the dance. Start asking who's dancing next.
Write the archive well, and know it's the archive.
The decisions, the rationale, the “why we chose this” behind an autonomous agent's actions are genuinely archive-shaped, and the most dangerous thing you can do is let that record be confident but unverifiable. Chain of Consciousness is the archive done right for agents: a verifiable, tamper-evident record of what an agent decided and why, so the decision-trail survives the people (and the model versions) who held it. It captures the part that is archivable, honestly, and doesn't pretend to hold the repertoire, which is exactly the discipline this essay argues for.
Hosted Chain of Consciousness · See a verified chain · pip install chain-of-consciousness · npm install chain-of-consciousness