Developer Onboarding
Structured process for new developers to become productive quickly, from environment setup to understanding team architecture and processes.
What it is
Developer onboarding is the process of taking a new team member from "just arrived" to "I'm productive." Good onboarding reduces this time from weeks to days.
Components
- Environment setup: dev containers, setup scripts
- Documentation: AGENTS.md, README, architecture decision records
- First PR: small task to familiarize with the flow
- Buddy system: an assigned companion for questions
- Checklist: verifiable list of completed steps
Metrics
| Metric | Target | How to measure |
|---|---|---|
| Time to first commit | < 1 day | Start date → first commit |
| Time to first merged PR | < 1 week | Start date → first merge |
| Time to first production deploy | < 2 weeks | Start date → first deploy |
| New developer satisfaction | > 4/5 | Survey at 30 days |
Automation
pnpm install && pnpm devshould work in under 5 minutes- Dev containers eliminate "works on my machine"
- AGENTS.md as guide for humans and AI agents
Anti-patterns
- "Ask Juan" — all knowledge in one person, not in documentation
- 3-day setup — if onboarding takes more than half a day, the environment needs automation
- Outdated onboarding docs — worse than having none, because they generate frustration and distrust
Why it matters
Onboarding time is a direct metric of development platform health. If a new engineer takes weeks to become productive, the problem is not the engineer — it is the lack of documentation, golden paths, and reproducible environments.
References
- The Manager's Path — Camille Fournier. Includes sections on effective onboarding.
- An Elegant Puzzle — Will Larson, 2019. Engineering management systems including onboarding.
- DX: Developer Experience — Addy Osmani, 2024. Book on developer experience including onboarding.
Related content
- Developer Experience
Discipline focused on optimizing developer productivity, satisfaction, and effectiveness through well-designed tools, processes, and environments.
- Documentation as Code
Practice of treating documentation with the same tools and processes as code: versioned in Git, reviewed in PRs, and automatically generated when possible.
- Golden Paths
Recommended, pre-configured paths for common development tasks incorporating best practices, reducing cognitive load for teams.
- Local Development
Practices and tools for creating productive development environments on the developer's machine, replicating production as closely as possible.