There’s a person on every long-lived system who just knows. Ask them why the nightly job runs before the sync and they answer immediately; ask where to look when a certain symptom appears and they name the file. The natural response is to want that written down, and so there’s a push for documentation — and then the documentation gets written, and people still ask that person. Not because the docs are bad. Because what that person has isn’t a set of facts; it’s a model of how the system moves, and the facts are outputs of the model rather than the model itself.

The distinction matters because the two transfer differently. Facts can be written and read: this endpoint returns that shape, this service owns that table, the deploy runs on this schedule. A model is the sense of which things are connected to which, what’s fragile and what’s solid, what happens when you push here. It’s what lets someone predict — to guess, before looking, where a bug probably lives and be right more often than chance. You can write a hundred true sentences about a system and still not convey the thing that makes an experienced person’s guesses good, because their guesses come from a compressed sense of the shape of the whole, and prose delivers it one linear piece at a time.

Which doesn’t make documentation useless — it makes it a different tool than people expect. Docs are scaffolding for building a model, not a substitute for one. They dramatically accelerate someone who is actively constructing an understanding: they answer the small questions fast so the learner can spend their attention on the structure instead of on scavenging basics. But they only work on someone who is doing the building. Handing a thorough wiki to a person who hasn’t yet worked in the system produces recall, not intuition — they can quote the doc and still have no idea where to start when something breaks.

Models get built by doing, and specifically by doing things that produce feedback. Fixing a bug teaches you more about a subsystem than reading it, because a bug forces you to form a hypothesis and then find out you were wrong, which is the mechanism by which a model actually updates. Being on call teaches the failure modes in a way no runbook does. Making a change and watching what it disturbs teaches the coupling. This is why the fastest way to spread knowledge through a team isn’t a documentation sprint — it’s distributing the work that builds models: rotating who handles incidents, letting someone unfamiliar take the change in an area they don’t know, pairing on the gnarly thing instead of assigning it to whoever will finish it soonest.

So the practical stance is to hold both. Write down the facts, especially the surprising ones and the reasons behind them, because that’s cheap and it’s the scaffolding everything else stands on. But don’t mistake having written them for having transferred understanding, and don’t measure knowledge distribution by how thorough the wiki is. Measure it by whether more than one person can be dropped into a strange failure and make good guesses. That capability is only built by people doing the work, being wrong, and correcting — and the shortest path to a second person who “just knows” is to make sure someone besides the first person has been in there enough times to develop the same instincts.