Onboarding is the most measurable documentation test there is: drop a new engineer into the codebase and watch where they get stuck. Every place they have to interrupt a teammate is a place the docs failed. This checklist is organised the way a new hire actually experiences their first weeks — access, environment, orientation, first contribution — with the documentation that should carry each stage.
Stage 0: Before day one
- Repository access (and the right permission level).
- Cloud / infra accounts, SSO, VPN if relevant.
- Communication tools, calendars, the team’s channels.
- A named onboarding buddy — one person whose explicit job is to unblock them.
Stage 1: A running environment
The first concrete win is getting the project running locally. This is where a good README or onboarding doc earns its keep — and where stale setup steps cause the most damage, because the new hire can’t yet tell whether they made a mistake or the doc is wrong.
- Clone the repo.
- Install dependencies with the exact, current command.
- Copy the example environment file and fill in what’s needed.
- Run the project; confirm it’s up.
- Run the tests; confirm they pass.
Every command here should be copy-pasteable and verified against the current state of the project. “Run the dev server” is not a step; npm run dev is.
Stage 2: Codebase orientation
Now the new hire needs a map. Not every file — the shape:
- What does this system do, and for whom? The product context, in plain language.
- How is it structured? The main modules and what each is responsible for — a folder map with purpose, not a raw tree dump.
- How does a request flow through it? A diagram from entry point to data layer beats paragraphs.
- What’s the data model? The core entities and how they relate.
- What does it talk to? External services, integrations, and what each is for.
This is exactly the documentation that’s most expensive to maintain by hand and most likely to be stale — which is why so many teams onboard by having a senior engineer explain it verbally, over and over. Generating this orientation layer from the code, kept current automatically, turns a recurring interruption into a page the new hire reads on their own.
Stage 3: A real first contribution
Reading only goes so far; people learn a codebase by changing it. Have a scoped starter task ready — small enough to finish in a day or two, real enough to matter, and touching the core paths so they learn the important parts. The first pull request is the moment onboarding becomes real.
- A well-defined starter issue with clear acceptance criteria.
- A pointer to the relevant code and docs for that area.
- A fast, friendly first code review.
- Their change shipped — the confidence builder that matters most.
Stage 4: Ongoing context
- Who owns which part of the system (and how to reach them).
- How to get help without feeling like a burden.
- The team’s conventions — branching, commits, reviews, releases.
- Where decisions are recorded, so they can learn the “why.”
The documentation multiplier
Notice how much of this checklist is really a documentation test. Access and a starter task are logistics; the rest — environment setup, orientation, conventions, ownership — succeeds or fails on whether the docs are accurate and findable. A team with current docs onboards engineers in days. A team with stale docs onboards them by interrupting seniors for weeks, paying the stale-documentation tax at the worst possible time.
The orientation layer — overview, module map, request flows, data model, integrations — is precisely what VizRepo generates from your repository and keeps current on every commit, in the wiki your team already uses. New hires get an accurate map on day one instead of a verbal tour on day five. For the workflow behind it, see how to keep documentation up to date.