Your New Engineers Learn the System by Interrupting Your Senior Engineers

A new senior engineer joins your team. You hired them because they've done this work before, and you expect them to be shipping within a few weeks. Instead, their first month goes to archaeology. They read code to work out what calls what. They ask why the billing service has its own copy of the customer table. They find a deployment script nobody has touched in two years and wonder whether it still matters. Every question they can't answer from the code becomes a Slack message to one of the three people who have been around long enough to know.

Those three people are your most expensive engineers, and onboarding has quietly become part of their job. Every hire you make costs you weeks of the newcomer's time and a slice of your senior engineers' time, and the cost repeats with every hire. When one of those three leaves, some of what they knew leaves with them.

This is an internal documentation problem. Most engineering teams treat it as a culture problem or a hiring problem, which is why it rarely gets fixed.

The knowledge exists. It just isn't written down.

The questions new engineers ask are remarkably consistent. Watch a few onboardings and you'll hear the same ones:

• What are the major pieces, and how does a request move through them?
• Why is it built this way? In particular, why is it built in the strange way it obviously is?
• How do I get a working environment, and how does code reach production?
• What will hurt me? Which parts are fragile, which tests are flaky, which tables you never write to directly.

The code answers none of these well. Code shows what the system does today, not why it ended up that way or which of its oddities are deliberate. A README covers setup, if you're lucky, and it was accurate for whoever wrote it on the machine they had at the time.

Why "we'll document it later" never arrives

Teams don't skip internal documentation because they think it's worthless. They skip it because nobody owns it, it never competes well against roadmap work, and the people who could write it are the ones with the least spare time. Customer-facing docs at least have a customer asking for them. Internal docs only have a new hire, and new hires are reluctant to complain about anything in their first month.

So the knowledge gets passed on verbally, one onboarding at a time. That works until the team grows faster than the senior engineers can talk.

Four documents that do most of the work

You don't need a wiki with two hundred pages. Most of the onboarding burden can be lifted by four kinds of document, kept in the repository next to the code they describe.

1. A system overview. One page, maybe two, with a diagram of the major components and a plain-language walkthrough of what happens when a typical request comes in. Name the services, the data stores, and the external dependencies. This is the map every newcomer currently draws for themselves on a whiteboard.
2. Architecture decision records. In 2011, Michael Nygard proposed recording each significant architecture decision as a short document with a title, the context that forced the decision, the decision itself, its status, and its consequences, good and bad. His point was that a new team member who doesn't understand why something was done has two bad options: accept it blindly or change it blindly. A decision record gives them a third option, which is to read the reasoning and decide whether it still holds.
3. A first-week path. Not a list of links. A sequence: set up the environment, run the tests, make a trivial change, get it reviewed, and watch it deploy. Each step should say what success looks like, so a newcomer knows when they're stuck and should ask.
4. Runbooks for the parts that page people. If a service wakes someone up at night, the steps to diagnose and recover it should not live only in the head of the person who usually gets woken up.

A decision record can be short. This is about the right size:

# ADR-014: Billing keeps its own copy of customer records

Status: Accepted

## Context
Invoice generation must succeed even when the accounts service is down,
and finance requires invoices to reflect customer details as they were
on the billing date.

## Decision
Billing stores a snapshot of the customer fields it needs, refreshed
from account change events.

## Consequences
Billing data can lag account changes by a few minutes. Never write to
billing.customers directly; correct the source record instead.

That last line alone can save a newcomer from a very bad afternoon.

How to start without stopping the roadmap

You can make real progress on this in a few weeks without a documentation initiative.

• Use your next new hire as the audit. Ask them to keep a running list of every question they had to ask a person. That list is your documentation backlog, already prioritized by real need.
• Record the explanations you're already giving. When a senior engineer walks someone through the architecture, record it with permission. A rough transcript is most of a first draft.
• Write decision records going forward first. Back-filling every past decision is a project. Writing one for each new decision is a habit, and a handful of back-filled records for the strangest parts of the system covers most of the questions.
• Review docs in the same pull request as the change. If a change makes the system overview wrong, the fix belongs in that PR. Docs kept in a separate wiki are easy to forget when the code changes.
• Give each document a named owner. Ownership is what separates documentation from a pile of pages.

The same principle applies here as it does to customer documentation: organize around what the reader is trying to do, not around how your team is structured. I wrote about that failure in Your Documentation Is Organized Like Your Org Chart, and Your Users Can't Find Anything. A new engineer is a reader with a very specific task: become useful without exhausting your senior staff.

Why an outside writer can get this done

The hardest part of internal documentation isn't writing. It's extracting what the senior engineers know without consuming the time you were trying to protect. An outside technical writer who can read the code does the slow part: tracing the system, drafting the overview and decision records, and arriving at interviews with specific questions instead of "so, how does it all work?" Your engineers spend a few focused hours reviewing for accuracy instead of weeks writing from a blank page.

I spent decades as a software engineer before I became a technical writer, so I can follow a request through your services, read your deployment configuration, and talk with your engineers about trade-offs in their own terms.

Making the next onboarding shorter

If every new hire still learns your system by interrupting the same few people, the knowledge exists; it just hasn't been written down where the next person can find it. I'd be glad to look at what your team has now and help you decide which documents would make the biggest difference to your next onboarding. You can reach me through the contact page.