Developer Onboarding Builder

Create frictionless first-day experiences for new team members.

Core Workflow

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

Onboarding Documentation Structure

ONBOARDING.md Template

markdown

# 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)

bash

# 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)

bash

# Copy environment template
cp .env.example .env

Edit .env with these values:

code

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)

bash

# 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)

bash

pnpm dev

Expected output:

code

✓ 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)

bash

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:

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

Estimated time: 2-4 hours

Success criteria:

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

Day 2-3: Codebase Tour

Project Structure Overview

code

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)

•src/app/page.tsx - Homepage (entry point)
•src/app/api/users/route.ts - Simple API endpoint
•src/services/user.service.ts - Business logic example
•src/components/ui/button.tsx - UI component pattern
•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

typescript

// 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

typescript

// 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

•Morning: Check Slack, pull latest main
•Standup: Share yesterday, today, blockers
•Code: Work on assigned tickets
•Lunch: Team usually eats at 12:30
•Afternoon: Continue coding, review PRs
•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:

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:

•Hard refresh (Cmd+Shift+R)
•Clear .next folder: rm -rf .next
•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

Learning Resources

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

code

**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! 🚀

code


## 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)