Onboarding Guide Template

Overview

An onboarding guide accelerates new team member productivity by providing a clear path from day one to first meaningful contribution. See README Template for project docs and Contributing Guide for contribution standards. It reduces the burden on existing team members and ensures consistency.

When to Use

• A new developer joins your team
• You want to reduce repetitive “how do I…” questions
• You need to document tribal knowledge
• Your team is growing rapidly

Template

# Onboarding Guide

Welcome to the team! This guide will help you get up and running.

## Day 1: Accounts and Access

- [ ] Email and Slack/Teams account created
- [ ] Git repository access granted
- [ ] CI/CD platform access configured
- [ ] Development environment credentials received
- [ ] Calendar invites sent for team standups and rituals

## Day 1-2: Environment Setup

See [Environment Setup Guide Template](/docs/templates/environment-setup-guide-template) for detailed instructions.

### Required Tools
| Tool | Version | Purpose | Install Link |
|------|---------|---------|-------------|
| Node.js | 20.x | Runtime | [nodejs.org](https://nodejs.org) |
| Docker | Latest | Containers | [docker.com](https://docker.com) |
| Git | 2.40+ | Version control | [git-scm.com](https://git-scm.com) |

### Repository Setup
```bash
git clone git@github.com:org/repo.git
cd repo
npm install
npm run dev

Verify: http://localhost:4321 should show the application.

Day 2-3: Codebase Overview

Architecture

[High-level diagram or description of system components]

Key Directories

Directory	Purpose
/src/components	Reusable UI components
/src/pages	Route definitions
/src/lib	Shared utilities and schemas
/tests	Test suites

Conventions

• Branch naming: feature/description, bugfix/description
• Commit messages: Conventional Commits
• Code style: Enforced by ESLint and Prettier

Day 3-5: First Contributions

Good First Issues

Look for issues labeled:

• good first issue
• help wanted
• documentation

First Tasks

Day	Task	Goal
3	Fix a typo or update docs	Learn the PR workflow
4	Write a unit test	Understand testing standards
5	Pick a small bug	End-to-end contribution flow

Week 2+: Deeper Dive

• Attend architecture overview session
• Read ADRs in /docs/adr/
• Shadow an on-call rotation (observation only)
• Pair program with a teammate

Resources

• Team Wiki
• API Documentation
• Runbooks
• Architecture Decision Records

Questions?

Your onboarding buddy is: [Name] Slack: @username | Email: name@company.com

## Key Sections

| Section | Purpose |
|---------|---------|
| **Accounts & Access** | Remove blockers on day one |
| **Environment Setup** | Standardized dev environment |
| **Codebase Overview** | Architectural context |
| **First Contributions** | Clear path to first PR |
| **Resources** | Where to find more info |

## What Works

- **Make it useful**: Every item should be a checkbox or command
- **Assign a buddy**: New hires need a human point of contact
- **Keep it current**: Review and update quarterly
- **Start simple**: Day 1 should not overwhelm

## Common Mistakes

- **Outdated instructions**: Broken links or changed processes
- **Missing credentials**: Access requests that take days
- **No buddy system**: New hire isolated without help

## Frequently Asked Questions

### How long should onboarding take?

Useful onboarding spans 2-4 weeks. The first week focuses on environment setup and small contributions. Weeks 2-4 deepen domain knowledge and increase contribution complexity.

### What if the new hire is remote?

Remote onboarding requires more structured check-ins. Use video calls for pairing sessions, maintain a shared onboarding checklist in a project management tool, and over-communicate during the first month.

### Should onboarding be the same for junior and senior developers?

No. Senior developers need less hand-holding with tools but more context on architecture and domain. Junior developers need more guidance on workflows, code standards, and feedback cycles.


## Variants

| Context | Approach | Notes |
|---------|----------|-------|
| Startup | 1-week onboarding | Focus on setup and first ticket |
| Enterprise | 30-day onboarding with mentor | Include culture, processes, compliance |
| Remote | Onboarding with equipment shipping | Include VPN setup, remote access |
| Open source | Contributor onboarding | Focus on dev setup and PR workflow |

## Onboarding Example: Week 1

```text
=== Onboarding: Backend Engineer ===

Day 1: Setup and Access
  Morning:
    [ ] Laptop and equipment delivered
    [ ] Accounts created: Google Workspace, Slack, GitHub, Jira
    [ ] Repo access: read permissions on all repos
    [ ] VPN configured
    [ ] Local environment: Node.js, Docker, PostgreSQL
    [ ] Clone main repo and run locally
    [ ] 1:1 meeting with assigned mentor
  Afternoon:
    [ ] Tour of internal documentation
    [ ] Read general architecture (docs/architecture.md)
    [ ] Join team Slack channels
    [ ] Configure notifications and profile

Day 2-3: Code Immersion
  [ ] Read main service README
    [ ] Understand directory structure
    [ ] Understand data model
    [ ] Understand request flow
  [ ] Run service locally
    [ ] Make a test request
    [ ] Check logs
    [ ] Connect debugger
  [ ] Read 3 recent PRs to understand review flow
  [ ] Meeting with Product Owner: understand roadmap
  [ ] Meeting with Tech Lead: understand code standards

Day 4-5: First Contribution
  [ ] Assign a "good first issue" ticket
  [ ] Create branch following naming convention
  [ ] Implement the change
  [ ] Write tests
  [ ] Create PR with clear description
  [ ] Address code review comments
  [ ] Merge PR
  [ ] Celebrate first contribution!

End of Week 1:
  [ ] Retro 1:1 with mentor: what worked, what did not
  [ ] Retro 1:1 with manager: expectations, questions
  [ ] Identify learning areas for Week 2-4
  [ ] Set up recurring 1:1 meetings

How do we assign an effective mentor?

A good mentor is patient, knows the codebase, and has availability. Assign the mentor before day 1 — the mentor should prepare the onboarding. The mentor should: do daily 1:1s during the first week, be available for Slack questions, pair program on the first ticket, and give continuous feedback. Do not assign the busiest engineer as mentor — availability is more important than knowledge. Rotate the mentor if the chemistry does not work. The mentor is not responsible for the new engineer’s performance — they are responsible for facilitating onboarding. Recognize the mentor’s work in performance reviews.

How do we measure if onboarding was successful?

Measure: time to first contribution (target: < 5 days), time to full autonomy (target: < 30 days), new engineer satisfaction (survey at end of week 1 and month 1), and 90-day retention. Ask for structured feedback: what was useful, what was missing, what would you change. Compare onboarding across different engineers to identify patterns. If an engineer takes more than 2 weeks to make their first PR, the onboarding has a problem. If more than 1 engineer reports the same gap, fix the onboarding. Onboarding is an investment — good onboarding reduces time to productivity.

End of document. Review and update quarterly.