The Onboarding Reality Day 1: - 'Here's your laptop' - 'Clone the repo' - 'Ask Bob if you need help' - 'Good luck' Week 1: - 'Where's the API documentation?
The Cost of Bad Onboarding Direct costs: - Senior dev time: 2-4 hours/day answering questions - New hire salary during unproductive period - Delayed project delivery Indirect costs: - Senior dev context switching (23 min to refocus) - New hire frustration (retention risk) - Team velocity drop - Knowledge stays tribal Math: - Senior dev: $150K salary = $75/hour - 2 hours/day x 60 days = 120 hours - Cost: $9,000 per new hire, just in senior time Structured onboarding pays for itself. What New Devs Need Week 1: Environment - Machine setup - Access permissions - Dev environment working - Can run and test locally Week 2: Architecture - System overview - Service boundaries - Data flow - Where things live Week 3-4: First Contribution - Small, well-defined task - Full context provided - Clear success criteria - Review and feedback Month 2: Independence - Pick from backlog - Minimal hand-holding - Knows who to ask what - Contributing regularly Structured Onboarding Board Create onboarding template: Day 1-2: Setup - [ ] Laptop configured - [ ] Git access granted - [ ] Slack/Teams added - [ ] Email working - [ ] Local environment running Day 3-5: Learn - [ ] Architecture overview doc read - [ ] Codebase tour completed - [ ] Key services understood - [ ] Meet team members Week 2: Explore - [ ] First bug fix (assigned) - [ ] First code review given - [ ] First code review received - [ ] Deployment process understood Week 3-4: Contribute - [ ] First feature (small) - [ ] Pair programming session - [ ] On-call shadow (if applicable) - [ ] Documentation contribution Checklist ensures nothing forgotten.
Onboarding Tasks with Context Good onboarding task: Title: Fix date formatting in user profile Context: - User settings page: /src/components/UserProfile.vue - Date utility: /src/utils/dateFormatter.js - Related to: [link to previous discussion] What to do: - Date shows 'MM/DD/YYYY' but should be user's locale - Use existing formatDate() function How to test: - Change browser locale - Verify date format changes Resources: - [Link to i18n documentation] - [Link to similar PR] Ask: @sarah for questions about i18n Context prevents 'where do I find this?' Documentation That Works Essential docs: 1. Getting Started - Clone, install, run - Copy-paste commands - Troubleshooting common issues 2.
Architecture Overview - System diagram - Service responsibilities - Data flow - Key decisions explained 3. Development Workflow - Branch naming - PR process - Review expectations - Deployment steps 4.
Who's Who - Team members - Responsibilities - Who to ask for what Keep updated (biggest failure: outdated docs). Buddy System Assign onboarding buddy: Buddy responsibilities: - Answer questions (first resort) - Daily check-in (week 1) - Weekly check-in (month 1) - Code review first PRs - Introduce to team Buddy benefits: - Leadership experience - Forced documentation (explains to explain) - Fresh eyes on process Rotate buddy role.
Everyone benefits from teaching. First Task Selection Ideal first task: - Well-defined scope - Touches important code - Has clear acceptance criteria - Not on critical path - Documentation available - Someone available for questions Bad first task: - Vague requirements - Critical deadline - Legacy code nobody understands - 'Just figure it out' First task sets tone.
Make it winnable. Pair Programming for Onboarding Structured pairing: Session 1: Observer - New dev watches - Senior explains thinking - Questions encouraged Session 2: Driver - New dev types - Senior guides - Mistakes are learning Session 3: Navigator - New dev directs - Senior types - Tests understanding Pairing accelerates learning.
2 hours pairing > 2 days solo. Code Review as Learning New hire code review: First PRs: - Detailed feedback - Explain 'why', not just 'what' - Link to style guides - Positive reinforcement Reviewing others: - Start week 2 - Low-stakes PRs - Builds understanding - Different perspective valuable Code review teaches codebase.
Onboarding Metrics Track onboarding success: - Time to first PR merged - Time to first solo task - Time to independent work - Questions asked per day (should decrease) - Buddy time spent (should decrease) Target: - First PR: day 5 - Solo task: week 3 - Independent: month 2 Measure. Improve.
Repeat. Common Onboarding Failures 1.
'Ask anyone' - Nobody owns onboarding - Questions fall through cracks - Inconsistent information 2. Outdated documentation - Setup guide from 2 years ago - Dead links - Wrong commands 3.
Information overload - 47 docs to read day 1 - No prioritization - Overwhelm, not learning 4. No first task - Week of 'getting up to speed' - No hands-on learning - Builds anxiety 5.
Shadow and pray - 'Watch Bob work' - Passive learning is slow - Active contribution is faster Onboarding Wiki Central knowledge base: - Getting started guide - Architecture documentation - Process documentation - FAQs - Who's who - Glossary Link from onboarding tasks. Update when questions repeat.
'If you asked, someone else will too' -> Add to wiki. 30-60-90 Day Plan 30 days: - Environment complete - First features shipped - Team relationships built - Process understood 60 days: - Working independently - Contributing to planning - Reviewing others' code - Finding own tasks 90 days: - Full team member - Mentoring next hire - Improving process - Ownership of area Clear milestones.
Clear expectations. GitScrum Onboarding Setup 1.
Create onboarding template board 2. Tasks with full context 3.
Link documentation in wiki 4. Assign buddy as team member 5.
Track progress visibly 6. First real task in sprint 7.
Measure time to productive New developer: - Sees all onboarding tasks - Context in every task - Documentation linked - Progress visible - Integrated into sprint Onboarding becomes process. Not afterthought.
$8.90/user/month. 2 users free.
The GitScrum Advantage
One unified platform to eliminate context switching and recover productive hours.
