Onboarding new engineers to the architecture: one page, one diagram, one walkthrough

Prepare four things before the new engineer arrives: an architecture overview of one or two pages, the current diagram, a first-week agenda with actual time blocks, and a named buddy who owns the daily check-ins for the first month. Everything else is available on request and should stay that way.

Measure week one with three signals rather than a feeling. Did the development environment work on day one. Did they open and merge a small pull request by day five. Do they know who to ask for what. All three are observable, and all three fail for reasons documentation can fix.

The reason to cap the overview at two pages is not attention span, it is that a longer document cannot be kept accurate. A two page overview has maybe fifteen falsifiable claims and someone can verify them in ten minutes before a new joiner starts. A forty page wiki has hundreds, and nobody checks any of them.

Pick the most common path through the system, usually the one that carries the most traffic or the most revenue, and follow it in order: where the request arrives, what authenticates it, what validates it, what writes, what reads, what fires asynchronously afterwards, and where it shows up in logs and metrics. Stop at every hop and open the actual file.

This works because it produces a spine. Everything else the new engineer learns for the next three months attaches to a hop on that path, and a hop is easier to attach to than a noun on a boxes-and-arrows chart. It also surfaces the parts of the system where the team itself is unsure, which is information the manager wants.

Name the repository directory at each hop and have the new joiner write them down as they go. The artefact they leave the session with is a map from box to directory, in their own words, which is the single most reused note anyone takes in week one. If the architecture file already has that table, they are checking it rather than building it, which is a much faster session.

Week one walkthrough, one request, ninety minutes:

  1. Entry point        cmd/api/routes.go            open it
  2. Auth               internal/auth                who issues the token
  3. Validation         internal/validate            where the schema lives
  4. Write path         internal/store/orders.go     which table, which index
  5. Async fan-out      internal/events              which queue, which consumers
  6. Observability      dashboards/orders            find this request in the logs

Leave with: the six directories above, written down, plus one question
per hop that nobody in the room could answer.

The people who read onboarding documentation are the people least able to correct it. A new joiner who spots something wrong lacks the confidence and the context to fix it in week one, and by the time they have both they no longer need the document and have forgotten what confused them.

The window for capture is roughly weeks two to four. Late enough that they can tell a real error from their own misunderstanding, early enough that they still remember being lost. Make fixing the onboarding page an explicit expectation in that window, ideally as their second or third pull request, and you get a document maintained by exactly the right people.

Split the material by decay rate, the same way you would split any other document. Intent, boundaries and team conventions change once or twice a year and are worth writing carefully. The inventory of services, modules and their wiring changes constantly and should not be written by hand at all. See keep onboarding docs up to date.

A generated inventory also solves a problem the buddy cannot: it reads the whole tree, not the part anyone remembers. Repository sync walks the tree once and takes at most forty files, 250KB in total and 30KB per file, in a priority order that puts infrastructure, containers and CI ahead of application code, with per-class ceilings so one directory of a hundred models cannot crowd everything else out. Alongside those files it carries a summary of the top three directory levels with file counts, which is how the picture ends up naming directories the walkthrough never opened.

A repository index: one line per repository saying what it is and whether it is still alive. Dead repositories that nobody archived are the most reliable way to waste a new engineer first week.

The current diagram as a URL, not a screenshot in a slide deck. When the diagram comes from repository sync, the picture they open in month three is still the current one, which matters because week one material gets re-read exactly when someone is under pressure. It also survives their own edits: a node they drag while reading is more than twelve pixels from where the sync left it, so the next regeneration puts it back where they moved it.

The architecture file, the ADR index, the runbook for the service they will be on call for, and the name of their buddy. Five links. Anything longer than that is a library, and libraries are for month two.

• Keep onboarding docs up to date
• Tribal knowledge in engineering teams
• ARCHITECTURE.md: the codebase map
• Repo to diagram: repository sync
• Live embeds for onboarding pages