Onboarding Docs

Onboarding Documentation Skill

Generate comprehensive onboarding documentation for new developers.

When to Use

• Creating documentation for new team members
• Generating architecture overviews
• Building local development setup guides
• Creating guided code walkthroughs
• Documenting architecture decisions (ADRs)

Reference Documents

• Architecture Overview - High-level system documentation
• Setup Guide - Local development setup patterns
• Code Tour - Guided codebase walkthrough patterns
• Decision Log - Architecture decision records (ADR)

Documentation Structure

Recommended Layout

docs/
├── onboarding/
│   ├── README.md              # Welcome and navigation
│   ├── architecture.md        # System architecture
│   ├── setup.md               # Local development setup
│   ├── code-tour.md           # Guided codebase tour
│   └── decisions/             # Architecture Decision Records
│       ├── 001-database.md
│       ├── 002-api-design.md
│       └── template.md
├── api/                       # API documentation
├── deployment/                # Deployment guides
└── troubleshooting/           # Common issues

Core Principles

1. Progressive Disclosure

Start with high-level concepts, then dive deeper:

Level 1: What does this system do? (1 paragraph)
Level 2: What are the main components? (architecture diagram)
Level 3: How do they interact? (sequence diagrams)
Level 4: Implementation details (code references)

2. Task-Oriented Structure

Organize around what developers need to DO:

✓ "How to set up the development environment"
✓ "How to add a new API endpoint"
✓ "How to debug authentication issues"

✗ "The Authentication Module"
✗ "Database Schema"
✗ "Configuration Options"

3. Working Examples

Every concept should have a working example:

✓ Code snippets that can be copy-pasted
✓ Complete working examples in a separate repo/directory
✓ Links to relevant test files as examples

✗ Pseudo-code that doesn't compile
✗ Incomplete snippets
✗ "Exercise for the reader" scenarios

4. Keep It Current

Documentation should be treated as code:

- Version control all documentation
- Review docs in PRs that change behavior
- Automate doc validation where possible
- Include "last verified" dates

Content Templates

Welcome Document

# Welcome to [Project Name]

## Quick Links
- 🚀 [Setup Guide](./setup.md) - Get your local environment running
- 🏗️ [Architecture](./architecture.md) - Understand the system
- 🗺️ [Code Tour](./code-tour.md) - Navigate the codebase
- 📚 [API Docs](../api/README.md) - API reference

## First Day Checklist
- [ ] Read the architecture overview
- [ ] Complete local setup
- [ ] Run the test suite
- [ ] Make a small change and deploy to staging

## Getting Help
- Slack: #team-channel
- On-call: @oncall-rotation
- Documentation issues: File a PR

Architecture Document

# System Architecture

## Overview
[1-2 paragraph system description]

## System Diagram
[ASCII diagram or link to diagram]

## Components
### [Component 1]
- **Purpose:** [What it does]
- **Technology:** [Tech stack]
- **Location:** `src/components/...`
- **Depends on:** [Other components]

## Data Flow
[Sequence diagram or description]

## Key Decisions
- [Why we chose X over Y](./decisions/001-xxx.md)

Verification Checklist

Before finalizing onboarding docs:

• New developer can complete setup in < 30 minutes
• All code examples compile/run
• All links are valid
• Diagrams are up-to-date
• No references to removed/renamed components
• Contact information is current