onboarding-docs
This skill should be used when generating developer onboarding documentation including architecture overviews, setup guides, code tours, and decision records.
📖 中文导读:This skill should be used when generating developer onboarding documentation including architecture overviews, setup guides, code tours, and decision records. 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: onboarding-docs description: This skill should be used when generating developer onboarding documentation including architecture overviews, setup guides, code tours, and decision records.
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