Developer Onboarding Builder

Create frictionless first-day experiences for new team members.

Core Workflow

1. Assess prerequisites: Identify required tools and access
2. Create setup guide: Step-by-step environment configuration
3. Design first task: Choose appropriate starter assignment
4. Add time estimates: Set expectations for each step
5. Document common issues: Preemptive troubleshooting
6. Introduce team: Context on people and structure
7. Provide codebase tour: Walkthrough of key areas

Onboarding Documentation Structure

ONBOARDING.md Template

# Welcome to [Team/Project Name]! 🎉

This guide will help you get set up and productive on your first day.

**Estimated completion time:** 2-3 hours

## Before You Start

### Access Checklist

- [ ] GitHub organization access
- [ ] Slack workspace invitation
- [ ] Email account setup
- [ ] VPN credentials (if remote)
- [ ] Cloud console access (AWS/GCP/Azure)
- [ ] CI/CD dashboard access
- [ ] Project management tool (Jira/Linear)

### Tools to Install

- [ ] Node.js 20+ (via [Volta](https://volta.sh/))
- [ ] pnpm 8+
- [ ] Docker Desktop
- [ ] PostgreSQL 15+
- [ ] VS Code or preferred editor
- [ ] Git configured with your work email

## Day 1: Environment Setup

### Step 1: Clone Repository (5 min)

```bash
git clone git@github.com:company/project-name.git
cd project-name
```

Why: Get the codebase on your machine

Troubleshooting:

• SSH key not working? See GitHub SSH setup
• Permission denied? Ask your manager to verify GitHub access

Step 2: Install Dependencies (10 min)

# Install Volta (Node version manager)
curl https://get.volta.sh | bash

# Install dependencies
pnpm install

Expected output: "Dependencies installed successfully"

Troubleshooting:

• pnpm not found? Restart terminal or run volta install pnpm
• Installation hangs? Check VPN connection

Step 3: Configure Environment (10 min)

# Copy environment template
cp .env.example .env

Edit .env with these values:

DATABASE_URL=postgresql://postgres:password@localhost:5432/projectname_dev
REDIS_URL=redis://localhost:6379
API_KEY=ask-team-for-dev-key

Get credentials from:

• Database: Local setup (see next step)
• API keys: Ask @alice or @bob on Slack #dev-onboarding
• External services: Check 1Password vault "Dev Credentials"

Troubleshooting:

• Can't find credentials? Post in #dev-onboarding
• Missing env var? Check .env.example for all required variables

Step 4: Setup Database (15 min)

# Start PostgreSQL with Docker
docker run --name project-postgres \
  -e POSTGRES_PASSWORD=password \
  -p 5432:5432 \
  -d postgres:15

# Run migrations
pnpm db:migrate

# Seed with test data
pnpm db:seed

Expected output: "Migration complete. Database seeded."

Verify: Open http://localhost:5432 and check for tables

Troubleshooting:

• Port 5432 already in use? Kill existing process: lsof -ti:5432 | xargs kill
• Migration fails? Drop and recreate: pnpm db:reset

Step 5: Start Development Server (5 min)

pnpm dev

Expected output:

✓ Ready on http://localhost:3000

Test: Open http://localhost:3000 - you should see the homepage

Troubleshooting:

• Port 3000 in use? Kill process or change PORT in .env
• Build errors? Clear cache: rm -rf .next && pnpm dev

Step 6: Run Tests (5 min)

pnpm test

Expected output: All tests passing ✓

If tests fail:

• First time? This is a bug! Report in #dev-help
• Known issue? Check #dev-help pinned messages

Day 1: Your First Task

Task: Fix a Starter Issue

We've labeled some issues as good-first-issue for new team members.

Goal: Successfully complete one small PR to learn our workflow

Steps:

1. Browse good first issues
2. Pick one that interests you (or ask for suggestion in #dev-onboarding)
3. Comment on the issue: "I'll take this!"
4. Create a branch: git checkout -b fix/issue-123-description
5. Make your changes
6. Write/update tests
7. Run pnpm lint and pnpm test
8. Commit following conventions
9. Push and create PR
10. Request review from your mentor

Estimated time: 2-4 hours

Success criteria:

• Branch created with proper name
• Code changes made
• Tests written/updated
• All checks passing
• PR created with description
• Code reviewed and merged

Mentors: @alice (backend), @bob (frontend), @charlie (full-stack)

Day 2-3: Codebase Tour

Project Structure Overview

src/
├── app/              # Next.js routes (start here!)
│   ├── api/          # API endpoints
│   └── (auth)/       # Authentication pages
├── components/       # React components
│   ├── ui/           # Base UI components
│   └── features/     # Feature-specific components
├── lib/              # Utilities and helpers
│   ├── api/          # API client
│   ├── hooks/        # Custom React hooks
│   └── utils/        # Helper functions
├── services/         # Business logic layer
└── types/            # TypeScript definitions

Key Files to Understand

File	What It Does	When You'll Touch It
src/app/layout.tsx	Root layout & providers	Adding global providers
src/lib/db.ts	Database client	Database queries
src/lib/auth.ts	Authentication logic	Auth-related features
src/middleware.ts	Request middleware	Adding auth/redirects

Walking Tour (Read These Files in Order)

1. src/app/page.tsx - Homepage (entry point)
2. src/app/api/users/route.ts - Simple API endpoint
3. src/services/user.service.ts - Business logic example
4. src/components/ui/button.tsx - UI component pattern
5. src/lib/hooks/useUser.ts - Custom hook example

Exercise: Find the code that handles user registration. Hint: Start at the API route!

Common Patterns

API Route Pattern

// src/app/api/[resource]/route.ts
export async function GET(req: Request) {
  // 1. Validate auth
  // 2. Parse request
  // 3. Call service layer
  // 4. Return response
}

Service Layer Pattern

// src/services/[resource].service.ts
export class UserService {
  async create(data: CreateUserDto) {
    // 1. Validate data
    // 2. Business logic
    // 3. Database operation
    // 4. Return result
  }
}

Week 1: Learning Path

Day 1

• Complete environment setup
• Fix first issue
• Meet your team (schedule 1:1s)

Day 2-3

• Read codebase tour documents
• Complete second issue (medium complexity)
• Review 2-3 PRs from teammates

Day 4-5

• Work on first feature (with mentor pairing)
• Attend team standup/planning
• Set up development tools (linters, extensions)

Team Structure

Engineering Team

Alice (@alice) - Tech Lead

• Approves architecture decisions
• Code review on complex PRs
• Ask: System design questions

Bob (@bob) - Senior Backend Engineer

• Database and API expert
• Ask: Backend, performance questions

Charlie (@charlie) - Senior Frontend Engineer

• UI/UX implementation
• Ask: React, styling questions

Your Manager (@manager)

• Weekly 1:1s on Fridays 2pm
• Career development discussions
• Ask: Process, priorities, career questions

Communication Channels

• #dev-general - General development discussion
• #dev-help - Ask questions, get unstuck
• #dev-onboarding - New member support
• #dev-releases - Release announcements
• #dev-alerts - Production alerts

Meeting Schedule

• Daily Standup - 10:00 AM (15 min)
• Sprint Planning - Mondays 2:00 PM (1 hour)
• Team Retro - Fridays 4:00 PM (45 min)
• Tech Talks - Thursdays 3:00 PM (30 min)

Development Workflow

Daily Workflow

1. Morning: Check Slack, pull latest main
2. Standup: Share yesterday, today, blockers
3. Code: Work on assigned tickets
4. Lunch: Team usually eats at 12:30
5. Afternoon: Continue coding, review PRs
6. End of day: Update ticket status, push work

PR Review Guidelines

When reviewing PRs:

• Check code quality and style
• Verify tests cover changes
• Run the code locally if significant
• Ask questions if unclear
• Approve when satisfied

Getting Code Reviewed

When requesting review:

• Self-review first
• Add clear description
• Link related issues
• Tag appropriate reviewers
• Address feedback promptly

Common Gotchas

Database

Problem: relation "users" does not exist Solution: Run migrations: pnpm db:migrate

Problem: Seed data not appearing Solution: Reset database: pnpm db:reset

Development Server

Problem: Changes not reflecting Solution:

1. Hard refresh (Cmd+Shift+R)
2. Clear .next folder: rm -rf .next
3. Restart dev server

Problem: Port already in use Solution: Kill process: lsof -ti:3000 | xargs kill

Environment

Problem: Missing environment variable Solution: Check .env.example, add to your .env

Problem: API key not working Solution: Verify it's the dev key, not prod (ask team)

Resources

Documentation

• Architecture Overview
• API Reference
• Contributing Guide
• Style Guide

Learning Resources

• Next.js Documentation
• Prisma Guides
• TypeScript Handbook

Internal Resources

• Company Wiki: https://wiki.company.com
• Design System: https://design.company.com
• API Playground: https://api-dev.company.com

Getting Help

When You're Stuck (5-15-30 Rule)

• 5 minutes: Try to solve it yourself
• 15 minutes: Search docs, Stack Overflow, past issues
• 30 minutes: Ask in #dev-help with context

Good Question Template

**What I'm trying to do:** [goal]
**What I tried:** [attempts]
**Error message:** [full error]
**Environment:** [OS, Node version, etc.]
**Related code:** [link to file/line]

Who to Ask

• Setup issues: #dev-onboarding or #dev-help
• Code questions: #dev-help or your mentor
• Process questions: Your manager
• Urgent/production: #dev-alerts

Week 1 Checklist

By end of week 1, you should have:

• Completed environment setup
• Fixed 2-3 good-first-issues
• Created first feature PR
• Met with all team members
• Attended all team meetings
• Read key documentation
• Understood development workflow
• Know how to get help

Feedback

We're always improving onboarding! Please share:

• What went well?
• What was confusing?
• What's missing?

Share in: #dev-onboarding or with your manager

---

Welcome to the team! We're excited to have you here! 🚀

## Onboarding Best Practices

### Time Estimates
- Be realistic with timing
- Include buffer for troubleshooting
- Track actual time vs estimated

### Progressive Complexity
- Day 1: Setup and simple task
- Week 1: Understanding patterns
- Month 1: Independent features

### Clear Success Criteria
- Checklist for each step
- Objective completion markers
- Regular check-ins

### Preemptive Troubleshooting
- Document known issues
- Provide solutions upfront
- Update based on new dev feedback

### Human Connection
- Introduce team members
- Schedule 1:1s
- Provide mentors

## First Task Selection Criteria

Good first task should:
- [ ] Be completable in 2-4 hours
- [ ] Touch multiple areas lightly
- [ ] Have clear acceptance criteria
- [ ] Require PR and review
- [ ] Be genuinely useful (not busy work)
- [ ] Have mentor availability

**Examples:**
- Fix typo in error message (touches: frontend, i18n, testing)
- Add validation to API endpoint (touches: backend, testing, docs)
- Improve loading state (touches: frontend, UX, components)

## Documentation Components

### Essential Sections
1. Prerequisites and access
2. Step-by-step setup with time estimates
3. First task assignment
4. Codebase tour
5. Team structure
6. Communication channels
7. Common issues and solutions
8. Resources and next steps

### Optional but Valuable
- Video walkthrough
- Pair programming schedule
- Reading list
- Architecture diagrams
- Glossary of terms

## Maintenance

### Keep Updated
- Review after each new hire
- Update tool versions
- Refresh access instructions
- Add new common issues

### Collect Feedback
- Exit survey after week 1
- Regular check-ins
- Track time to productivity
- Document pain points

## Output Checklist

Complete onboarding package includes:

- [ ] ONBOARDING.md with step-by-step guide
- [ ] Time estimates for each step
- [ ] First task identified and documented
- [ ] Team structure and communication
- [ ] Troubleshooting for common issues
- [ ] Links to all necessary resources
- [ ] Checklists for progress tracking
- [ ] Feedback mechanism
- [ ] Mentor assignments
- [ ] Expected timeline (day/week/month)