Engineering Onboarding That Works

bad_onboarding_symptoms:
  for_new_hires:
    - Sitting idle waiting for access
    - No clear first tasks
    - Don't know who to ask
    - Feel like a burden
    - Imposter syndrome intensifies

  for_teams:
    - Constant interruptions for basic questions
    - Same questions answered repeatedly
    - New hire frustration spreads
    - Slow time to productivity

  for_company:
    - Extended ramp-up time
    - Early attrition
    - Poor employer reputation
    - Wasted hiring investment

onboarding_impact:
  time_to_productivity:
    poor_onboarding: 6-12 months
    good_onboarding: 1-3 months

  retention_correlation:
    - Strong onboarding: 82% retention at 1 year
    - Weak onboarding: 50% consider leaving within year

  cost_of_turnover:
    - 50-200% of annual salary
    - Knowledge loss
    - Team disruption

onboarding_dimensions:
  1_operational:
    focus: Can they work?
    includes:
      - Hardware and accounts
      - Development environment
      - Access to systems
      - Basic tools working

  2_technical:
    focus: Do they understand the systems?
    includes:
      - Codebase orientation
      - Architecture understanding
      - Domain knowledge
      - Technical practices

  3_organizational:
    focus: Do they know how things work?
    includes:
      - Team processes
      - Communication norms
      - Decision-making
      - Who owns what

  4_social:
    focus: Do they feel connected?
    includes:
      - Team relationships
      - Mentorship
      - Company culture
      - Sense of belonging

pre_start_checklist:
  it_setup:
    - [ ] Laptop ordered and configured
    - [ ] Email account created
    - [ ] Slack/Teams access
    - [ ] Calendar access
    - [ ] VPN configured

  access_requests:
    - [ ] GitHub/GitLab
    - [ ] Cloud accounts
    - [ ] Internal tools
    - [ ] Documentation systems

  logistics:
    - [ ] First day schedule sent
    - [ ] Building access (if office)
    - [ ] Remote setup instructions
    - [ ] Contact info for questions

  personal_touch:
    - [ ] Welcome email from manager
    - [ ] Team intro scheduled
    - [ ] Buddy assigned and notified

day_one_goals:
  1_working_setup:
    - Can access email and chat
    - Can reach required systems
    - Development environment starts working

  2_met_the_team:
    - Introduced to immediate team
    - Met manager 1:1
    - Buddy introduced

  3_not_overwhelmed:
    - Clear about next steps
    - Knows who to ask
    - Has something to do

day_one_schedule:
  morning:
    - Welcome and setup verification
    - HR essentials (brief)
    - Manager 1:1 (expectations, first weeks)

  afternoon:
    - Team introduction
    - Buddy pairing starts
    - First task: Get dev environment running
    - End: Check-in, questions

week_one_structure:
  day_1: Setup and introductions
  day_2: Codebase orientation with buddy
  day_3: Architecture overview session
  day_4: First small task (real code)
  day_5: Team processes, check-in

first_task_criteria:
  properties:
    - Small and well-defined
    - Real (not make-work)
    - Achievable in 1-2 days
    - Touches real codebase
    - Has clear reviewer

  examples:
    - Fix a small bug
    - Add a simple feature
    - Update documentation
    - Add a test

  purpose:
    - Build confidence
    - Learn workflow (PR, review, deploy)
    - Celebrate small win

buddy_role:
  purpose: Human connection and daily support

  responsibilities:
    - Daily check-ins first week
    - Answer "stupid" questions
    - Explain unwritten rules
    - Navigate politics and culture
    - Be available

  not_responsible_for:
    - Technical training (that's broader)
    - Performance evaluation
    - Workload assignment

  buddy_selection:
    - Experienced enough to answer questions
    - Patient and helpful
    - Available for time commitment
    - Ideally on same team

  buddy_preparation:
    - Clear expectations
    - Time allocated
    - Materials provided

thirty_day_milestones:
  operational:
    - All access working smoothly
    - Dev environment mastered
    - Can deploy independently

  technical:
    - Understands main codebase areas
    - Completed several tasks
    - Understands architecture basics

  organizational:
    - Knows team processes
    - Participates in ceremonies
    - Understands how decisions are made

  social:
    - Knows team members
    - Starting to build relationships
    - Feels comfortable asking questions

learning_topics:
  week_1:
    - Development environment
    - Code structure overview
    - Git workflow
    - CI/CD basics

  week_2:
    - Architecture deep-dive
    - Key services and data flow
    - Testing approach
    - Monitoring and observability

  week_3:
    - Domain knowledge
    - Business context
    - Customer understanding
    - Product roadmap

  week_4:
    - Security practices
    - Incident response
    - On-call introduction
    - Team-specific practices

onboarding_documentation:
  getting_started:
    - Environment setup guide
    - First day checklist
    - Who's who guide
    - Communication channels

  technical:
    - Architecture overview
    - Service catalog
    - API documentation
    - Runbooks

  process:
    - Code review guidelines
    - Deployment process
    - Incident response
    - On-call expectations

  maintenance:
    - Keep docs current
    - New hire feedback improves docs
    - Assign ownership

documentation_practices:
  new_hire_contributions:
    - New hires update docs when they find gaps
    - Fresh eyes catch outdated content
    - Part of onboarding: improve docs

  regular_review:
    - Quarterly doc review
    - Remove stale content
    - Update for changes

onboarding_metrics:
  time_to_first_commit:
    target: Day 1-2
    measures: Operational readiness

  time_to_first_pr_merged:
    target: Week 1
    measures: Basic productivity

  time_to_independent_task:
    target: Week 3-4
    measures: Technical ramp-up

  90_day_survey:
    measures:
      - Confidence level
      - Clarity of role
      - Team integration
      - Onboarding quality rating

  retention_at_6_months:
    target: >95%
    measures: Overall success

feedback_collection:
  during_onboarding:
    - Daily check-ins week 1
    - Weekly check-ins month 1
    - 30-day survey

  post_onboarding:
    - 90-day retrospective
    - What worked, what didn't
    - Suggestions for improvement

  continuous_improvement:
    - Track common gaps
    - Update program based on feedback
    - Share learnings across teams

remote_onboarding:
  challenges:
    - No casual interaction
    - Harder to ask quick questions
    - Easy to feel isolated
    - Less osmotic learning

  adaptations:
    - More intentional social time
    - Video on for meetings
    - Daily standups with buddy
    - Virtual coffee chats

  tools:
    - Good video conferencing
    - Async documentation
    - Screen sharing for pairing
    - Chat for quick questions