Slow Onboarding Is a Dependency Graph Problem

Why new engineers take months

A new engineer joins a platform team and is told to read. Read the docs, read the runbooks, read the design docs, read the code. The reading is necessary, but it does not transfer the thing that makes an experienced engineer effective, which is a mental model of how the pieces relate. That model took the existing team years to build, largely by accident, through incidents and pull requests and conversations.

Prose is a poor medium for relationships. A document can describe one service well. It struggles to express that this service reads from that database, which is written by a job owned by another team, which depends on a credential rotated by a third. Each of those facts is a sentence, and the sentences live in different documents or in nobody's document at all. What a new engineer needs is not more sentences. It is the graph those sentences describe.

The two questions that block everyone

Strip away the specifics and almost every blocked moment in a new engineer's first months reduces to one of two questions.

• Who owns this? Not in the abstract, but right now, for this service or this module or this dataset. Ownership that exists only in a wiki page is ownership that is probably wrong.
• What breaks if I change it? Who calls this, what does it call, and what happens at each edge when the contract changes.

These are graph questions. Who owns this is an attribute lookup on a node. What breaks is a traversal over edges. When the graph is legible, each is a few seconds of work. When it is tacit, each becomes a conversation, and conversations do not scale across a team of eight hundred engineers spread over time zones.

The cost is not only the new engineer's time. It is the senior engineer's time, repeatedly interrupted to answer questions that a lookup could answer. System knowledge becomes a bottleneck located in a small number of people, and every one of those people is a single point of failure for the organisation's understanding of itself.

Ownership boundaries

Ownership is the highest-value attribute you can attach to a node, and the one most often maintained inconsistently. Teams track ownership in CODEOWNERS, in a service catalogue, in an on-call tool, in a spreadsheet, and in the heads of the people involved. These sources disagree, and when they do, the most recent one wins, which means the truth depends on who you ask.

A legible graph does not require inventing a new source of ownership. It requires picking one representation and connecting the others to it, so that a change in the code owner file is reflected in the model and the on-call rotation resolves to the same team. The value shows up in small moments. An alert fires and the responder knows who to page. A security review asks who can approve a change and gets an answer without a meeting.

Ownership boundaries also do the work that team structures are supposed to do. When every node has an owner, you can see where a service is owned by a team that no longer exists, or where a critical path depends on a group of one. Unowned nodes are a signal, not a nuisance.

Blast radius

Blast radius is the other side of the same traversal. Given a change to a node, the set of nodes that can be affected is the transitive closure of its reverse dependencies. That set is the thing a reviewer actually needs, and it is almost never what a file-level diff shows.

Consider a change to a shared library used by forty services. The pull request shows a small diff in one repository. The blast radius shows forty consumers, three of which are in the critical path for checkout and one of which is owned by a team that is not in the review. A reviewer with the graph sees a different change than a reviewer without it, and reviews are where small changes become system-wide risk.

Blast radius also changes how incidents are handled. When a service degrades, the first question is what else will degrade. An engineer who can answer that in the first minutes is working with information rather than intuition.

Making the graph legible

The instinct when onboarding is slow is to write more documentation. That instinct is understandable and mostly wrong. More prose adds reading, not understanding, and it decays alongside everything else. The fix is to make the graph legible: a single representation of services, datasets, and the relationships between them, with ownership attached and reconciliation against deployment so it stays current.

Once that exists, onboarding changes shape. A new engineer does not start with a reading list. They start from the service they own, walk its dependencies, and see which team to ask and what the consequences of a change are. They build the same mental model the senior engineers have, but in weeks instead of months, and without taking those engineers out of their work to build it for them.