I’ve been onboarded three times at new jobs. At some places I was productive in two weeks, at others I was stuck in debug mode for two or three months. I now lead two small teams, and I know what made the difference.
Onboarding done right means the new engineer ships a real PR in their second week. Done wrong, they’re still saying “I’m setting up my environment” in standup in their second month.
Here’s my six-part process.
1. Environment ready on day one
The biggest time sink is the local dev environment. A typo in the docker compose, a missing env variable, no access to an internal tool the docs reference, and so on.
The new engineer’s first day shouldn’t be spent setting up the environment. What I do:
- Docker compose or devcontainer.json so it’s “clone and run”
- Access (GitHub, Slack, DB, monitoring) granted automatically the moment the offer is signed. Not an IT ticket that takes five days.
- A README with “to get started” in 10 steps, each one tested
- A senior pairs on the setup: new engineer shares their screen, senior watches alongside
Any issues that come up get added to the README.
End of day one: the new engineer has run the test suite locally, fired up the dev server, and hit a simple “hello world” endpoint. A sense of progress.
2. Codebase tour: a guided walkthrough on day one
Telling a new engineer to “explore the codebase” is throwing them into a swamp. You need an organized tour.
A 1-hour walkthrough:
- Repository structure: which folder does what
- Main entry point: where requests come in, which route they go through, where they end up
- Data layer: how it reaches the DB, which ORM or query builder
- Test patterns: unit vs integration, where fake data lives
- CI/CD pipeline: PR -> tests -> deploy
- Production architecture: services, communication, monitoring
Record this session (Zoom recording plus upload to Notion or Google Drive). The next new engineer can watch the tour async.
3. Starter ticket: small but real work
The first piece of work you give the new engineer during onboarding needs to be chosen carefully.
Good starter ticket criteria:
- Finishable in 1 to 3 days (small)
- Real business value (not onboarding busywork)
- Ships to production (sense of accomplishment)
- Touches several parts of the codebase (frontend plus backend plus tests)
- Has natural questions to ask a senior
Bad starter ticket:
- “Write documentation” (not engaging)
- A super-complex feature (overwhelming)
- An obscure module (isolated, no learning)
- A trivia bug (no learning)
Something like “add a phone number field to the profile page” is ideal. Simple but touches the stack end to end.
4. Buddy system
Assign a senior “buddy” to the new engineer. Not the manager. They do a 15 to 30 minute quick-sync each day:
- What did they do yesterday, what will they do today
- Blockers
- Parts of the codebase they don’t get
- Process or culture questions
The buddy should be a senior engineer, not a manager (no hierarchy in the buddy relationship means it’s easier to talk openly). “No stupid questions” policy.
After 2 to 3 weeks, buddy check-ins get less frequent and the new engineer starts working independently.
5. Documentation: the runbook approach
Most teams’ documentation is either missing or stale. No help to a new engineer.
Critical documentation:
Architecture overview. One page, diagram plus paragraph. Shows the main services and how they talk.
Setup guide. Environment setup with exact commands. In README.md or SETUP.md.
Common tasks runbook. “How to run a migration”, “how to add a feature flag”, “how to pull production logs”, 15 to 20 common tasks, step-by-step.
Decisions log. Why this framework, why this DB, why this pattern. ADR (Architecture Decision Records) format works well.
Glossary. Team-specific terms. What does “tenant” mean here, what’s the difference between “run” and “job”, etc. These notes can be small and still cover a lot of ground.
A new engineer should be able to answer 60% of their questions from these docs. The other 40% goes to the buddy.
6. Feedback loop: 2-week, 1-month, 3-month check-ins
The manager should run structured check-ins with the new engineer.
2-week check-in:
- How is onboarding going? Where are you stuck?
- How do you feel about the team dynamic?
- Are expectations clear?
- Is anything missing (resources, access)?
1-month check-in:
- What have you learned so far?
- How did your first feature go?
- Is the roadmap clear?
- Is the buddy system working?
3-month check-in:
- How productive do you feel (1 to 10)?
- What would you change about the team?
- Where should your growth focus?
- Are long-term expectations aligned?
These check-ins give the manager structured data instead of relying on “is the new hire doing ok?” intuition. Missing pieces get caught proactively.
Common mistakes
1. “You’ll figure it out” approach. Senior engineer projects their own experience onto the junior and expects the same learning curve. No. Without docs plus walkthrough plus buddy, learning takes 3x longer.
2. Overwhelming first week. Cramming the entire system architecture, every tool in the chain, every process into one week. The information doesn’t stick, isn’t usable. Just-in-time learning is better.
3. Leaving them solo. Answering the new engineer’s questions with “Google it” when the answer is team-specific. Google doesn’t have team-specific answers. Reserve buddy time.
4. A flood of critical feedback on the first PR. A first PR that comes back with 50 review comments crushes the new engineer. I give the top 5 critical pieces of feedback, the rest in later iteration sessions.
5. Not maintaining onboarding docs. Docs get written, then never updated, and go stale in six months. Every new hire should be fixing the onboarding docs as they read them.
What “productive in two weeks” looks like
Success metrics:
- Environment fully working
- At least 1 PR merged (small but real)
- Attended at least 2 sprint ceremonies
- Done 1-on-1s with team members
- Can draw the main flow of the codebase
- Can give a meaningful update in standup
- Is comfortable talking with the buddy
I review these checks at the end of the week. The new engineer lands in either “on track” or “needs support”. Room for proactive intervention.
Closing lesson
The first two weeks are an investment in the new engineer. Manager and senior engineer should spend 20% of their time there. The return: a productive engineer in two weeks, a critical team member in six months.
Skipping it: still in debug mode at month three, frustration-based quit at month six.
Onboarding isn’t a luxury, it’s a requirement. Winning a hire isn’t just the offer, it’s managing the first 90 days.