A new person joins the team. Day one is the usual setup ritual: accounts, permissions, repositories, a few links to internal docs. By day three, something clicks. The first small task gets done. A unit test is added. A pipeline runs. A change lands.
Technically, it is going fine. Then comes the first “simple” question.
Why is this service split in this particular way? Why does everyone treat that module like it is made of glass? Why does a small change require a larger meeting? Why does the ticket say “do not touch this after 16:00”?
The answers are not in the documentation. They are not in the code. They live in the room.
That gap is the difference between technical knowledge and institutional knowledge.
Technical knowledge has a clean learning path. It is the how. It is portable. A person can pick up a framework, a toolchain, or a pattern, and the progress is visible. Tutorials help. Practice helps. Time helps. It often feels fair, because the rules do not move much.
Institutional knowledge is different. It is the why. It is local. It is shaped by the organization’s past decisions, its incidents, its customers, and its constraints. It includes the trade-offs that were made when deadlines were real and options were limited. It includes the scars from outages that only a few people remember clearly, plus the informal rules that grew around those moments.
Two companies can run the same technology and still feel like different worlds, because the invisible context is different.
That is also why institutional knowledge takes longer to acquire.
It is not just a volume problem, and it is not a talent problem. It is a contact problem. The fastest way to learn the “why” is usually a conversation with someone who has been close to the system for long enough to tell the story behind it. Often, the real learning happens in small moments: pairing on a change, reviewing a pull request together, watching how someone investigates an alert, hearing the backstory during a whiteboard sketch. Those moments compress years of context into something usable.
Cloud platforms develop their own versions of “the way things work here.” Data pipelines collect their own folklore. Security programs have their own unwritten rules. Microservices become a map of past reorganizations and past priorities. The technology may be newer, but institutional knowledge still exists, because it is not about age. It is about context.
So here is the real question behind all of this: If technical skills are relatively easy to acquire, what are teams doing to pass on the “why” without relying on luck, long tenure, or being in the right room at the right time?
Some teams do it well. They make space for story, not just instructions. They capture decision context alongside decisions. They treat onboarding as a relationship, not a checklist. They deliberately create opportunities for newer people to hear the history, learn the boundaries, and understand what matters.
Other teams struggle, and the symptoms look familiar. People do work that is correct, but not aligned. Changes create surprises. The same questions come up again and again. The knowledge remains trapped in a few heads, and those people become bottlenecks without intending to.
Does this split show up in your domain too?
Is the “how” relatively quick to learn, while the “why” takes much longer? Does in-person contact accelerate that learning in a way that documentation still struggles to match? And is this a mainframe-flavored problem, or simply a universal part of complex systems?
Comment with your take, and mention your domain. The interesting part is comparing notes across environments that look different on the surface, but may be identical underneath.