By Arjun Mehta
New engineers take 6 months to reach full productivity. In a 60-person engineering org, that's 30 person-months of lost capacity per year. At $200K fully-loaded salary, that's $1M in wasted productivity annually.
Most of that time isn't spent learning the job. It's spent understanding a codebase nobody adequately explained to them.
Good onboarding cuts this to 6 weeks. The investment is 40-80 hours of senior engineer time. The return is $500K+ per hire per year.
Why Onboarding Fails
Most companies do onboarding by accident, not by design. Here's what happens:
Day 1: laptop setup, "you'll understand once you're in there." Week 1: working on trivial features while slowly learning architecture. Weeks 2-4: first real feature, multiple revisions because they misunderstood the system. Months 2-6: ramping speed, discovering why things are the way they are through painful trial and error.
The problem is tribal knowledge transfer. The system exists. But understanding why it's structured that way doesn't.
The Three-Phase Onboarding That Works
Phase 1: Pre-Start (Before Day 1)
Send the new hire this before they start. They review it. You save 2-3 weeks of discovery.
Architecture diagram. One page. Shows main components and how they connect.
System walkthrough. How a user request flows through your system.
Critical decisions. Why do you use microservices? Why does that legacy module exist? Why is that constraint there?
Code examples. How you handle auth. How you structure tests. How you deploy. Actual examples from your codebase.
Common patterns. "This is how we write API endpoints. This is how we handle errors."
This is 2-3 hours of prep work that saves 2-3 weeks of discovery. The ROI is absurd.
Phase 2: Week 1 - Code Overview
Day 1: Environment setup. They can run the app locally. They can run tests. By end of day, they understand how to get from code to running.
Day 2-3: Guided codebase tour. This is a working session, not a lecture. "Here's the payment module. Walk me through how payments flow." They read code. You answer questions. They discover patterns. Go 2-3 levels deep. They should understand the critical path, not every detail.
Day 4-5: First code task. Something visible. Something low-risk. Something that uses most of the codebase. "Add a validation to the email field" or "Write a test for this function."
Goal: They've touched the critical code. They've shipped something. They're no longer intimidated.
Phase 3: Weeks 2-6 - Ramping Features
Assign features from a pre-planned onboarding roadmap:
Week 2: Small feature, 1-2 services, 3-day estimate. They'll probably take 5 days. That's fine. They're learning.
Week 3: Slightly harder feature, 2-3 services, 4-day estimate.
Week 4: Complex feature, needs architectural understanding, 5-day estimate.
Week 5: Feature that's ambiguous, requires judgment, 6-day estimate.
Week 6: Feature they own end-to-end, asking for help strategically.
Each feature teaches something new. Each is bigger than they can currently handle alone, but achievable with help. They learn by shipping, not by reading.
By end of week 6, they should be at 80% productivity. By week 8, fully productive.
The Runbook That Saves Hours
Before they start, create a runbook:
Getting to "hello world" (5 minutes). How to clone the repo. How to set up dependencies. How to see the app running.
Running tests (2 minutes). One command. What if it fails? Here are the most common issues and how to fix them.
Deploying locally (3 minutes). How to run the full system locally.
Common issues. Missing dependencies, port conflicts, database setup, permissions. For each: what the error looks like, what causes it, how to fix it.
Who to ask. Not "Slack someone." Specific people: "For deployment questions, ask Sarah." "For database questions, ask Tom."
This runbook eliminates the first 5-10 hours of onboarding friction. That's 1-2 weeks of time saved per hire.
Documentation That Actually Helps
Don't write comprehensive documentation. Write task-specific documentation.
Instead of: "Here's our authentication system." Write: "To add a new permission: (1) Add to the enum, (2) Update the middleware, (3) Add the test. Here's an example PR that did this."
Instead of: "Here's our deployment process." Write: "To deploy: (1) Push to main, (2) CI runs tests (5 min), (3) Check the deploy dashboard. If failed, see [#troubleshooting]. It's live in 10 minutes."
Specific, actionable docs save 2-3 hours per week during onboarding.
Pair Programming and Code Review
The fastest onboarding happens with pair programming and detailed code review.
Week 1: Pair programming. They drive, senior engineer watches. They write code, experienced engineer catches misunderstandings immediately.
Weeks 2-6: They write, senior engineer reviews thoroughly. Feedback is: "I see what you're doing. Here's a pattern we use instead. Here's why." Not: "This is wrong."
Good code review accelerates onboarding by 30%.
Measuring Success
Track these metrics for every new hire:
Days to first commit: should be less than 1 day.
Days to first deployed code: should be less than 3 days.
Days to independent shipping: should be less than 10 days.
Days to productive velocity (80%+): should be 4-6 weeks.
If any metric is significantly longer, investigate. Usually it's:
Environment setup too complicated (fix the runbook) Architecture unclear (fix the overview) Tasks poorly defined (PMs need to define features better) Code review not detailed enough (reviewers need training)
The Template for Success
- Pre-start material (architecture, decisions, patterns, examples)
- Day 1 runbook (environment, tests, deploy locally)
- Guided codebase tour (understand critical path)
- Pre-planned ramping features (6 features, increasing difficulty)
- Pair programming and detailed code review (catch misunderstandings early)
- Task-specific documentation (not general, actionable)
Teams that nail these get new hires productive in 6 weeks instead of 6 months. The investment is 40 hours per hire. The payback is $500K+ per year.
You're not saving time by skipping onboarding. You're spending $500K to save $1K in short-term productivity.
Frequently Asked Questions
How do we allocate time for onboarding when we're shipping features? Onboarding is a force multiplier. 40 hours of investment saves 500+ hours of productivity loss over the year. Allocate 2 weeks before the hire starts for prep work. The senior engineer mentoring for a month is an investment, not a cost.
What if we can't pair program every day? You don't need to. 3-4 days in Week 1 is enough. After that, detailed code review is sufficient. The key is catching misunderstandings while they're small, not when they've already shipped bad code.
How do we keep onboarding material updated? Assign one engineer (rotating quarterly) as "Onboarding Owner." Their job: review material every quarter, update based on new hire feedback, keep runbooks current.