Onboarding into code nobody wrote

The old method assumed an author

Onboarding used to work roughly like this. A new person is given a small bug. They struggle. They ask the person who wrote that part. That person explains, including the history: why it is like that, what was tried, what broke last year. Over three months the new person acquires a working model of the system from the people who built it.

Every step of that assumes somebody remembers writing it. Where a service was largely generated, and where the changes were reviewed quickly, that person may not exist. The new joiner asks and gets a shrug, or worse, a plausible reconstruction that nobody can verify.

So onboarding has to be rebuilt to run without an author. That is doable and it needs to be explicit.

A first fortnight that works

Day 1 to 2: the trace. Give them one request and ask them to follow it end to end, writing down every file it touches in order, and to present that trace to somebody on the team. Not a bug. Not a ticket. Just the trace.

This works because it is verifiable (the files either are involved or are not) and because the presentation catches misunderstandings immediately. It is also the exercise that most reliably reveals how convoluted a path has become, which is information the existing team has stopped being able to see.

Day 3 to 4: the data model. Draw the main tables and their relationships from the schema, without looking at any documentation. Then compare against whatever documentation exists. The differences are the most valuable output: they show where the documents have drifted, which nobody notices from inside.

Week 1: a deliberately chosen bug. Not the easiest one. One that requires reading three parts of the system and cannot be fixed without understanding something. Sit with them for the first hour and then leave them to it.

Week 2: review a real change. Have them review a senior’s pull request, then have the senior read the review and respond to it properly. This is the reverse-review practice from earlier, and for a new joiner it is the fastest way to learn both the code and what this team considers important.

Ongoing: they own the documentation for what they learned. Every confusion becomes a paragraph. A new joiner is the only person who can see what is unclear, and that ability lasts about six weeks.

What to write down while somebody still knows

If you have a service whose author has left or whose history is a closed session, capture what remains before it goes entirely:

• The failure modes. What breaks, how often, what it looks like, what fixes it. This is the highest-value knowledge and it lives only in the people who have been paged.
• The oddities. What looks like a bug and is not. Each of these should become a comment and a decision record.
• The dependencies nobody expects. “The nightly job assumes this table is not being written to.”
• The things you must never do. “Do not run the backfill twice.”

A forty-minute conversation with the longest-serving person, recorded and turned into a page, is worth more than any generated documentation, because it consists entirely of things that are not in the code.

Bus factor as an operational property

Treat “how many people can explain and safely change this service” as a number you track, alongside whether the backups restore.

One is a risk. Zero is an outage waiting for a trigger, and zero is now reachable in a way it previously was not: a service can be built, deployed and running with nobody having ever held its model, which was not possible when somebody had to type all of it.

When the number is low, the remedies are ordinary: rotate the reviewer, run an incident drill on that service, have somebody make a deliberate small change to it, pair on the next feature. All cheap. All requiring somebody to decide they matter.

The check that costs ten minutes

Once a quarter, pick a service and ask a random engineer to explain, in five minutes, what it does, what its main failure mode is, and where its data lives.

Not as a test of the person. As a measurement of the team. If three people in a row cannot, you have found the service that will cause your worst incident, several months before it does.