The onboarding document that actually works

Onboarding documentation is written by someone who already knows the system, which means it is written from the wrong side of the knowledge gap.

The result is consistently: an architecture overview that is meaningless without context, a list of tools with no explanation of why, and no answer to any question a new person actually has.

what a new engineer actually needs, in order#

Day one: get something running.

Not understanding. Running. A new engineer who has the application running locally on day one is in a completely different position from one who is still fighting a dependency on day three.

This section should be a numbered list of commands that work. Tested. On a clean machine. Recently.

## get it running

1. Install prerequisites:  `brew bundle`   (or the equivalent — see below)
2. Copy the environment:   `cp .env.example .env`
3. Get secrets:            `./scripts/fetch-dev-secrets` (needs VPN)
4. Start dependencies:     `docker compose up -d`
5. Migrate:                `./scripts/db-reset`
6. Run:                    `pnpm dev`

You should see the app at http://localhost:5173 with seeded data.
Log in with dev@example.com / password.

If step 3 fails with "unauthorized", you need to be added to the
dev-secrets group — ask in #eng-onboarding.

That last paragraph — the anticipated failure with its resolution — is the part that separates a document that works from one that does not. Every step that has ever failed for anyone should have a note.

Day two: make a change and see it.

A guided first change. Something trivial and real: change a label, add a field, fix a typo in a template. All the way through: edit, test, review, merge, deploy.

The point is not the change. It is that they have now executed the entire delivery pipeline once, so every subsequent change is a variation on something they have done.

Day three to five: the map.

Now the architecture overview, and now it means something, because they have seen the system run.

Keep it to a page. What are the major pieces, what does each do, how do they talk. A diagram. Where the code for each piece lives.

Not a complete description. A map, at the resolution of "which building do I go to."

Week two: the why.

The decisions that are not obvious from the code. Why the database is structured that way. Why there is a queue between those two services. Why that module is frozen. Why the obvious approach to X does not work.

This is the highest-value and least-written documentation in any organization, because it exists only in the heads of people who were there. When they leave, it is gone, and the next person spends a year rediscovering it — usually by proposing the obvious approach and being told no.

the sections everyone forgets#

The glossary. Every organization has jargon: internal product names, acronyms, words used with a specific local meaning. A new person hears twenty of these in their first week and cannot ask about all of them without feeling stupid.

Write them down. This is a thirty-minute task with an outsized payoff.

Who to ask about what. Not the org chart. "Payments: ask Priya. Deploy pipeline: #platform-help. Anything about the legacy importer: Marcus, and be warned it is complicated."

The things that will surprise you. The test suite that fails on the first run until you seed a fixture. The service that takes four minutes to start. The one flaky test everyone knows about. The staging environment that resets on Sundays.

Every codebase has these. Writing them down converts "this is broken and I do not want to admit I cannot fix it" into "oh, that is expected."

What not to touch. Frozen modules, generated files, anything requiring a specific review.

the maintenance mechanism#

Onboarding docs rot faster than any other documentation, because the people who would notice the errors are the ones who no longer read it.

The fix: the last person onboarded owns it.

Every new engineer's first task is to follow the document, fix everything that was wrong, and add the things they had to ask about. Then they own it until the next person arrives.

This works because their frustration is fresh and their perspective is exactly the target reader's. It is the only mechanism I have seen that keeps these documents accurate.

the test#

Hand it to a new engineer and do not help them.

Time how long until they have the application running. Note every question they had to ask. Each question is a gap, with a measured cost.

Then fix them, and repeat with the next person.

Most teams have never done this and would be surprised by the result.