Developer Onboarding | First Commit in Days
Design structured onboarding for new developers using GitScrum's NoteVault documentation and starter tasks. Reduce time-to-first-commit from weeks to days.
13 min read
New developer onboarding can take weeks or months without structure, leaving newcomers confused and existing team members constantly interrupted. An effective onboarding program uses GitScrum's NoteVault for documentation, carefully designed starter tasks, and clear expectations to reduce time-to-first-commit from weeks to days. The goal isn't just technical setup—it's creating psychological safety and building relationships that enable long-term productivity.
Onboarding Philosophy
What Good Onboarding Achieves
ONBOARDING OUTCOMES:
┌─────────────────────────────────────────────────────────────┐
│ MEASURING ONBOARDING SUCCESS │
├─────────────────────────────────────────────────────────────┤
│ │
│ POOR ONBOARDING: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Week 1: "Read the wiki" (outdated, fragmented) ││
│ │ Week 2: "Shadow someone" (interrupts their work) ││
│ │ Week 3: "Pick any ticket" (no context, fails) ││
│ │ Week 4: Still asking basic questions ││
│ │ Month 2: Finally somewhat productive ││
│ │ Month 3: Still discovering tribal knowledge ││
│ │ ││
│ │ Result: New hire feels incompetent ││
│ │ Team frustrated by interruptions ││
│ │ First real contribution: 4-6 weeks ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ EFFECTIVE ONBOARDING: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Day 1: Environment works, first PR merged (docs fix) ││
│ │ Day 2-3: Complete 2-3 "good first issues" ││
│ │ Week 1: Paired on real feature with mentor ││
│ │ Week 2: Own first feature end-to-end ││
│ │ Week 3-4: Contributing at 50% capacity ││
│ │ Month 2: Full team member, mentoring next hire ││
│ │ ││
│ │ Result: New hire feels capable ││
│ │ Team gains contributor quickly ││
│ │ First real contribution: 2-3 days ││
│ └─────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
The 30-60-90 Day Framework
PROGRESSIVE EXPECTATIONS:
┌─────────────────────────────────────────────────────────────┐
│ ONBOARDING PHASES │
├─────────────────────────────────────────────────────────────┤
│ │
│ FIRST 30 DAYS: LEARNING │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Goals: ││
│ │ • Environment fully set up and working ││
│ │ • Understand codebase architecture ││
│ │ • Complete 5-10 small tasks ││
│ │ • Meet all team members 1:1 ││
│ │ • Know who to ask for what ││
│ │ ││
│ │ Success metric: Can run, test, deploy code ││
│ │ independently ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ DAYS 31-60: CONTRIBUTING │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Goals: ││
│ │ • Own 2-3 medium features end-to-end ││
│ │ • Participate in code reviews (giving + receiving) ││
│ │ • Attend and contribute to sprint ceremonies ││
│ │ • Start identifying improvements ││
│ │ ││
│ │ Success metric: Completing features with normal ││
│ │ level of support ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ DAYS 61-90: OWNERSHIP │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Goals: ││
│ │ • Own an area of the codebase ││
│ │ • Make architectural decisions (with guidance) ││
│ │ • Improve documentation based on experience ││
│ │ • Help onboard next new hire ││
│ │ ││
│ │ Success metric: Full team member, mostly independent ││
│ └─────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
Documentation in NoteVault
Onboarding Runbook
STRUCTURED DOCUMENTATION:
┌─────────────────────────────────────────────────────────────┐
│ NOTEVAULT ONBOARDING STRUCTURE │
├─────────────────────────────────────────────────────────────┤
│ │
│ 📓 Onboarding Guide │
│ │ │
│ ├─ 📄 Welcome & Team Overview │
│ │ • Who we are, what we build │
│ │ • Team roster with photos, roles, contact │
│ │ • Communication norms (when to Slack vs email) │
│ │ • Meeting schedule and expectations │
│ │ │
│ ├─ 📄 Day 1 Checklist │
│ │ ☐ Accounts created (GitHub, GitScrum, Slack) │
│ │ ☐ Repo cloned and running locally │
│ │ ☐ First PR merged (typo fix or README update) │
│ │ ☐ Introduced in team Slack channel │
│ │ ☐ 1:1 scheduled with manager │
│ │ ☐ Buddy assigned and intro meeting done │
│ │ │
│ ├─ 📄 Local Development Setup │
│ │ • Prerequisites (Node version, Docker, etc.) │
│ │ • Step-by-step setup instructions │
│ │ • Common errors and solutions │
│ │ • Verification: "You're done when tests pass" │
│ │ │
│ ├─ 📄 Architecture Overview │
│ │ • System diagram with component explanations │
│ │ • Key files and what they do │
│ │ • Data flow for common operations │
│ │ • "Start here" pointers for each area │
│ │ │
│ ├─ 📄 Development Workflow │
│ │ • Git branching conventions │
│ │ • PR process and review expectations │
│ │ • CI/CD pipeline overview │
│ │ • Deployment process │
│ │ │
│ └─ 📄 FAQ & Tribal Knowledge │
│ • "Why do we do X this way?" │
│ • Historical decisions and context │
│ • Common gotchas │
│ • Who knows what (expertise map) │
│ │
└─────────────────────────────────────────────────────────────┘
Keeping Docs Current
DOCUMENTATION MAINTENANCE:
┌─────────────────────────────────────────────────────────────┐
│ FRESH ONBOARDING DOCS │
├─────────────────────────────────────────────────────────────┤
│ │
│ RULE: New hire updates docs during onboarding │
│ │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Week 1 task for new hire: ││
│ │ ││
│ │ "As you follow the onboarding docs, fix any issues ││
│ │ you encounter. You are the best judge of what's ││
│ │ confusing or outdated because you're experiencing it ││
│ │ right now." ││
│ │ ││
│ │ Specifically: ││
│ │ • Fix incorrect instructions ││
│ │ • Add missing steps ││
│ │ • Clarify confusing sections ││
│ │ • Add troubleshooting for issues you hit ││
│ │ • Remove outdated information ││
│ │ ││
│ │ This is a REAL TASK with story points. ││
│ │ Not optional "if you have time." ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ QUARTERLY REVIEW: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Every quarter: ││
│ │ • Test setup docs on fresh machine ││
│ │ • Review with last 2 hires: what was missing? ││
│ │ • Archive outdated sections ││
│ │ • Update architecture diagrams ││
│ └─────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
Starter Tasks
Good First Issues
DESIGNING STARTER TASKS:
┌─────────────────────────────────────────────────────────────┐
│ IDEAL FIRST TASKS IN GITSCRUM │
├─────────────────────────────────────────────────────────────┤
│ │
│ CHARACTERISTICS OF GOOD STARTER TASKS: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ ✅ Small scope (1-4 hours) ││
│ │ ✅ Clear acceptance criteria ││
│ │ ✅ Touches real production code ││
│ │ ✅ Low risk if done incorrectly ││
│ │ ✅ Introduces one new concept ││
│ │ ✅ Has existing patterns to follow ││
│ │ ││
│ │ ❌ NOT: "Refactor the authentication system" ││
│ │ ❌ NOT: "Fix this bug" (with no context) ││
│ │ ❌ NOT: "Build the new feature" (too much scope) ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ EXAMPLE GOOD FIRST TASKS: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Task: Add loading state to user list ││
│ │ ││
│ │ Labels: good-first-issue, onboarding ││
│ │ Estimate: 2 points ││
│ │ ││
│ │ Description: ││
│ │ Currently the user list shows nothing while loading. ││
│ │ Add a loading spinner. ││
│ │ ││
│ │ Acceptance criteria: ││
│ │ ☐ Spinner shows while fetching users ││
│ │ ☐ Spinner matches existing pattern in ProductList ││
│ │ ☐ Test added for loading state ││
│ │ ││
│ │ Getting started: ││
│ │ 1. See how ProductList handles loading (src/components)││
│ │ 2. UserList is in src/features/users/UserList.tsx ││
│ │ 3. Use the <Spinner /> component from src/ui ││
│ │ ││
│ │ Ask @mentor if stuck for more than 30 minutes ││
│ └─────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
Progressive Task Complexity
TASK LADDER:
┌─────────────────────────────────────────────────────────────┐
│ INCREASING COMPLEXITY │
├─────────────────────────────────────────────────────────────┤
│ │
│ LEVEL 1 (Day 1): Proof of setup │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ • Fix typo in README ││
│ │ • Update outdated comment ││
│ │ • Add missing test case ││
│ │ ││
│ │ Purpose: Verify dev environment, learn PR process ││
│ │ Time: <1 hour ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ LEVEL 2 (Days 2-3): Small isolated changes │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ • Add field to existing form ││
│ │ • Implement simple component ││
│ │ • Write tests for existing function ││
│ │ ││
│ │ Purpose: Learn code patterns, build confidence ││
│ │ Time: 2-4 hours each ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ LEVEL 3 (Week 1): Feature slice │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ • Add new page with data fetching ││
│ │ • Implement CRUD for simple entity ││
│ │ • Add validation to existing form ││
│ │ ││
│ │ Purpose: Understand full stack flow ││
│ │ Time: 1-2 days ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ LEVEL 4 (Week 2+): Full features │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ • Own feature from design to deployment ││
│ │ • Debug and fix production issue ││
│ │ • Refactor subsystem with guidance ││
│ │ ││
│ │ Purpose: Real contribution, build ownership ││
│ │ Time: Multi-day ││
│ └─────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
Mentorship Model
Buddy System
ONBOARDING BUDDY ROLE:
┌─────────────────────────────────────────────────────────────┐
│ BUDDY RESPONSIBILITIES │
├─────────────────────────────────────────────────────────────┤
│ │
│ WHO: Experienced team member (not manager) │
│ │
│ DUTIES: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ FIRST WEEK: ││
│ │ • Daily 15-min check-in ││
│ │ • Pair on first tasks together ││
│ │ • Review all PRs same-day ││
│ │ • Available for "dumb questions" (no judgment) ││
│ │ • Introduce to team members ││
│ │ ││
│ │ WEEKS 2-4: ││
│ │ • 2-3 check-ins per week ││
│ │ • First reviewer on PRs ││
│ │ • Pair on complex tasks ││
│ │ • Navigate organizational questions ││
│ │ ││
│ │ MONTH 2+: ││
│ │ • Weekly check-in ││
│ │ • Transition to normal team relationship ││
│ │ • Retrospective on onboarding experience ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ BUDDY TIME ALLOCATION: │
│ Week 1: ~4 hours (20% of week) │
│ Week 2-4: ~2 hours (10% of week) │
│ Month 2: ~1 hour (5% of week) │
│ │
│ This is REAL WORK. Buddy tasks are reduced accordingly. │
│ │
└─────────────────────────────────────────────────────────────┘
Check-in Structure
PRODUCTIVE CHECK-INS:
┌─────────────────────────────────────────────────────────────┐
│ DAILY CHECK-IN FORMAT │
├─────────────────────────────────────────────────────────────┤
│ │
│ 15 MINUTES DAILY (Week 1): │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Questions (5 min): ││
│ │ 1. What did you work on yesterday? ││
│ │ 2. What are you working on today? ││
│ │ 3. What's confusing or blocking you? ││
│ │ ││
│ │ Buddy response (5 min): ││
│ │ • Answer questions ││
│ │ • Provide context on blockers ││
│ │ • Suggest who can help with specific issues ││
│ │ ││
│ │ Next steps (5 min): ││
│ │ • Identify pairing opportunities ││
│ │ • Schedule any needed deep-dives ││
│ │ • Set clear goal for today ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ WEEKLY CHECK-IN (Month 2+): │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ 30 minutes: ││
│ │ 1. What went well this week? ││
│ │ 2. What was frustrating? ││
│ │ 3. What do you still not understand? ││
│ │ 4. What would have helped you this week? ││
│ │ 5. What do you want to learn next? ││
│ └─────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
Psychological Safety
Creating Safe Environment
NEW HIRE PSYCHOLOGY:
┌─────────────────────────────────────────────────────────────┐
│ BUILDING CONFIDENCE │
├─────────────────────────────────────────────────────────────┤
│ │
│ COMMON NEW HIRE FEARS: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ "I'll ask a stupid question and look incompetent" ││
│ │ "Everyone else seems to know everything" ││
│ │ "I should have figured this out already" ││
│ │ "My code isn't as good as theirs" ││
│ │ "They made a mistake hiring me" ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ BEHAVIORS THAT BUILD SAFETY: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ ✅ "Great question, I didn't know that for months" ││
│ │ ✅ "Let me show you how I'd approach this" ││
│ │ ✅ "I made the same mistake when I started" ││
│ │ ✅ "Here's what's NOT documented anywhere..." ││
│ │ ✅ "Your fresh perspective found a real issue" ││
│ │ ││
│ │ ❌ "That's in the docs" (without helping find it) ││
│ │ ❌ "You should know that by now" ││
│ │ ❌ Sighing when asked questions ││
│ │ ❌ Criticizing PR without explaining why ││
│ │ ❌ "We've always done it this way" ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ EXPLICIT NORMS: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Tell new hires on Day 1: ││
│ │ ││
│ │ "You will ask questions we think are obvious. ││
│ │ That's EXPECTED. It means the docs are incomplete. ││
│ │ Your confusion helps us improve. ││
│ │ ││
│ │ If you're stuck for 30 minutes, ask. Don't wait. ││
│ │ We want interruptions in week 1. ││
│ │ That's how you learn faster." ││
│ └─────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
Tracking Progress
Onboarding Tasks in GitScrum
GITSCRUM ONBOARDING PROJECT:
┌─────────────────────────────────────────────────────────────┐
│ TASK VISIBILITY │
├─────────────────────────────────────────────────────────────┤
│ │
│ Create project: "Onboarding - [Name]" │
│ │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ BOARD COLUMNS: ││
│ │ ││
│ │ To Do │ In Progress │ Review │ Done ││
│ │ ──────┼─────────────┼────────┼────── ││
│ │ │ │ │ ││
│ │ [Setup│ [Starter │ │ [First PR ││
│ │ local│ Task #2] │ │ merged] ││
│ │ env] │ │ │ ││
│ │ │ │ │ [Intro ││
│ │ [1:1 │ │ │ meeting] ││
│ │ with │ │ │ ││
│ │ PM] │ │ │ ││
│ │ │ │ │ ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ Labels: │
│ • day-1, week-1, week-2, month-1 │
│ • technical, social, documentation │
│ │
│ Benefits: │
│ • New hire sees clear progress │
│ • Manager can track onboarding health │
│ • Nothing falls through cracks │
│ │
└─────────────────────────────────────────────────────────────┘