Onboarding Engineers Faster

By Michael Samuel Naeem · January 3, 2026 · 5 min read

A senior hire spent eleven days unable to run the app locally because the README referenced a deprecated Docker Compose file and secrets lived in a wiki page nobody linked. They almost accepted another offer out of boredom. Onboarding is not HR paperwork — it is product delivery infrastructure. Every day a capable engineer cannot merge is a day you paid full salary for zero throughput while they reverse-engineer tribal knowledge. Structured onboarding with measurable ramp milestones pays back in retention and team morale faster than another recruiting loop.

Pre-start: environment before day one

Ship laptop early with:

• Standard image (MDM, security baseline)
• SSO to GitHub/GitLab, Slack, VPN if required
• .env.example and working make setup tested in CI weekly

.PHONY: setup test run

setup:
	./scripts/check-prerequisites.sh
	cp -n .env.example .env || true
	docker compose up -d postgres redis
	npm ci && npm run db:migrate && npm run seed:dev

test:
	npm test

run:
	npm run dev

Run make setup in GitHub Actions on schedule — broken onboarding is a CI failure, not a surprise for hire #47.

Week one structure

Buddy system — not manager. Peer who answers "where is X?" within 15 minutes, introduces to stakeholders, reviews first PR with extra context. Rotate buddies to spread load.

Good first issues that teach

Label tickets explicitly:

good-first-issue: changes isolated to `packages/billing-ui`
estimated: < 4 hours for someone new to repo
learning goals: PR process, component test patterns

Avoid "refactor auth" as first task. Docs fixes and missing test coverage are legitimate — they force repo traversal without production risk.

Architecture tour that sticks

One living document beats fifty stale Confluence pages:

# System map (15 min read)
## User request path
Browser → CloudFront → API (Go) → Postgres + Redis

## Repos
- `api/` — core backend, start here
- `web/` — Next.js frontend

## Where things break
- Payments: see runbook payments/on-call.md
- Deploy: GitHub Actions → ECS, main auto-deploys

## Local quirks
- Port 8080 not 3000 (historical)
- Feature flags: `DEV_FLAGS=checkout_v2` in .env

Link from README first paragraph. Record 20-minute Loom for async timezone hires.

30/60/90 expectations

Shared doc between manager and hire:

30 days: merged 3+ PRs, can run on-call shadow, knows team rituals
60 days: owns small feature end-to-end with review
90 days: on-call ready (if role includes), proposes improvement to area touched

Ambiguity kills confidence — write expectations even if flexible.

Measure and iterate

Dashboard from issue tracker:

• Days from start → first merged PR
• PR review turnaround for new hires (signal inclusion)
• 30-day survey: "I know who to ask" (1–5)

Retros on onboarding quarterly. If three hires hit the same Docker issue, fix Docker — do not add another Notion page.

Remote and timezone inclusion

• Overlap hours defined first week
• Record all architecture sessions
• Written decisions default — verbal standup context inaccessible async
• First PR paired via screen share optional, not mandatory embarrassment

Fast onboarding is respect: the org invested in hiring; earning ROI means unblocking hands on keyboard immediately.

First-week checklist for managers

Concrete actions for the hiring manager in week one:

Day 1:
□ Laptop provisioned and logged in before start time
□ Repo access granted (not pending IT ticket)
□ Buddy assigned and introduced
□ 30/60/90 plan shared in writing

Day 2-3:
□ Local dev environment working (paired session if needed)
□ First "good first issue" assigned with context
□ Architecture overview recording shared (not live-only)

Day 4-5:
□ First PR opened (even if small — docs fix counts)
□ Team rituals calendar shared (standup, retro, planning)
□ Key contacts list: who owns what system

Blockers on Day 1–3 are manager failures, not new hire failures.

Good first issue criteria

Effective starter tasks share these properties:

• Scoped: Completable in 1–3 days
• Low blast radius: Can't break production
• Touched by team recently: Code is familiar to reviewers
• Tests included: New hire learns test patterns
• Documented context: Link to relevant design doc or ticket

## Good first issue template
**Context:** [Why this change matters]
**Files to touch:** [Specific paths]
**Acceptance criteria:** [Testable outcomes]
**Who to ask:** [@buddy for questions]
**Estimated effort:** 1-2 days

Avoid: "Improve performance" or "Refactor auth module" as first tasks.

Onboarding documentation that works

Structure the onboarding doc as a task list, not a wiki:

/onboarding/
├── README.md          ← start here, day-by-day checklist
├── dev-setup.md       ← copy-paste commands, tested monthly
├── architecture.md    ← 1-page system diagram + key decisions
├── team-norms.md      ← PR process, review expectations, on-call
└── glossary.md        ← internal terms and acronyms

Test dev-setup.md monthly — broken setup instructions waste the entire first day.

Failure modes

• Access pending on Day 3 — new hire idle; manager didn't pre-provision
• No written 30/60/90 plan — ambiguity kills confidence
• Architecture explained once verbally — not recorded; inaccessible to async hires
• First task too large — week one ends without merged PR
• Same onboarding issue repeated — fix the root cause, not the doc

Production checklist

• Repo and tool access provisioned before start date
• 30/60/90 plan written and shared Day 1
• Good first issue assigned with context and acceptance criteria
• Dev setup doc tested monthly by existing engineer
• Architecture sessions recorded for async access
• Days-to-first-PR tracked and reviewed quarterly

Resources

• Google re:Work — onboarding
• GitLab onboarding handbook (public)
• The First 90 Days (Michael Watkins)
• Good first issues labeling (GitHub docs)
• Developer Experience surveys (DX)