majiayu000 Onboarding Documentation Skill
When to Use This Skill
Use this skill when:
- Onboarding Docs tasks - Working on developer onboarding documentation and learning paths
- Planning or design - Need guidance on Onboarding Docs approaches
- Best practices - Want to follow established patterns and standards
Overview
Create comprehensive developer onboarding documentation for accelerated productivity.
MANDATORY: Documentation-First Approach
Before creating onboarding docs:
- Invoke
docs-managementskill for onboarding patterns - Verify developer experience best practices via MCP servers (perplexity)
- Base guidance on industry onboarding standards
Onboarding Documentation Framework
Onboarding Documentation Layers:
┌─────────────────────────────────────────────────────────────────────────────┐
│ Day 1: Environment Setup │
│ • Development environment installation │
│ • Access provisioning and credentials │
│ • Tool configuration │
├─────────────────────────────────────────────────────────────────────────────┤
│ Week 1: Core Concepts │
│ • Architecture overview │
│ • Codebase orientation │
│ • Development workflow │
├─────────────────────────────────────────────────────────────────────────────┤
│ Month 1: Deep Dive │
│ • Domain knowledge │
│ • System internals │
│ • Advanced workflows │
├─────────────────────────────────────────────────────────────────────────────┤
│ Ongoing: Reference Materials │
│ • API documentation │
│ • Runbooks and procedures │
│ • Best practices and standards │
└─────────────────────────────────────────────────────────────────────────────┘
Onboarding Guide Template
# Developer Onboarding Guide
Welcome to [Project/Team Name]! This guide will help you get productive quickly.
---
## Quick Links
| Resource | Link | Purpose |
|----------|------|---------|
| Codebase | [GitHub Repo] | Source code |
| Documentation | [Docs Site] | Technical docs |
| Issue Tracker | [Jira/GitHub] | Tasks and bugs |
| CI/CD | [Azure DevOps/GitHub Actions] | Build pipelines |
| Monitoring | [Grafana/DataDog] | Metrics and alerts |
| Chat | [Slack/Teams] | Team communication |
---
## Day 1 Checklist
### Access Setup
- [ ] GitHub organization invite accepted
- [ ] Azure subscription access granted
- [ ] Slack/Teams workspace joined
- [ ] VPN configured (if applicable)
- [ ] Password manager setup
- [ ] MFA enabled on all accounts
### Development Environment
- [ ] IDE installed and configured
- [ ] Required SDKs installed
- [ ] Repository cloned
- [ ] Project builds locally
- [ ] Tests run successfully
### First Steps
- [ ] Read this onboarding guide
- [ ] Review team conventions
- [ ] Meet your onboarding buddy
- [ ] Schedule 1:1 with team lead
---
## Environment Setup
### Prerequisites
| Tool | Version | Installation |
|------|---------|--------------|
| .NET SDK | 10.0+ | [Download](https://dot.net) |
| Node.js | 22 LTS | [Download](https://nodejs.org) |
| Docker Desktop | Latest | [Download](https://docker.com) |
| Git | 2.40+ | [Download](https://git-scm.com) |
| VS Code / Rider | Latest | IDE of choice |
### Step-by-Step Setup
#### 1. Install Prerequisites
**Windows (winget):**
```powershell
winget install Microsoft.DotNet.SDK.10
winget install OpenJS.NodeJS.LTS
winget install Docker.DockerDesktop
winget install Git.Git
winget install Microsoft.VisualStudioCode
```
**macOS (Homebrew):**
```bash
brew install --cask dotnet-sdk
brew install node@22
brew install --cask docker
brew install git
brew install --cask visual-studio-code
```
#### 2. Clone Repository
```bash
# Clone the main repository
git clone https://github.com/org/project.git
cd project
# Install dependencies
dotnet restore
npm install
```
#### 3. Configure Environment
```bash
# Copy environment template
cp .env.example .env.local
# Edit with your values
code .env.local
```
**Required Environment Variables:**
| Variable | Description | How to Get |
|----------|-------------|------------|
| `DATABASE_URL` | PostgreSQL connection | Use local Docker or dev DB |
| `AZURE_CLIENT_ID` | Azure service principal | Request from team lead |
| `API_KEY` | External API key | 1Password vault |
#### 4. Start Development Environment
```bash
# Start infrastructure (database, cache, etc.)
docker compose up -d
# Run database migrations
dotnet ef database update
# Start the application
dotnet run
```
#### 5. Verify Setup
```bash
# Run tests
dotnet test
# Check API health
curl http://localhost:5000/health
```
**Expected Output:**
```json
{
"status": "Healthy",
"checks": {
"database": "Healthy",
"cache": "Healthy"
}
}
```
---
## Architecture Overview
### System Context
[Include C4 Context Diagram]
### High-Level Architecture
```text
┌─────────────────────────────────────────────────────────────────────────────┐
│ Load Balancer │
└─────────────────────────────────────────────────────────────────────────────┘
│
┌────────────────┼────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Web App │ │ API │ │ Worker │
│ (Blazor) │ │ (.NET) │ │ Service │
└──────────────┘ └──────────────┘ └──────────────┘
│ │ │
└────────────────┼────────────────┘
▼
┌─────────────────────┐
│ PostgreSQL │
└─────────────────────┘
```
### Key Components
| Component | Purpose | Tech Stack |
|-----------|---------|------------|
| Web App | User interface | Blazor, Tailwind CSS |
| API | Backend services | .NET 10, Minimal APIs |
| Worker | Background jobs | .NET Worker Service |
| Database | Data persistence | PostgreSQL 16 |
| Cache | Performance | Redis |
| Queue | Async messaging | Azure Service Bus |
---
## Codebase Orientation
### Repository Structure
```text
project/
├── src/
│ ├── Web/ # Blazor frontend
│ ├── Api/ # Backend API
│ ├── Worker/ # Background services
│ └── SharedKernel/ # Shared code
├── tests/
│ ├── Unit/ # Unit tests
│ ├── Integration/ # Integration tests
│ └── E2E/ # End-to-end tests
├── docs/ # Documentation
├── scripts/ # Utility scripts
├── .github/ # GitHub workflows
└── docker-compose.yml # Local development
```
### Key Files to Review
| File | Purpose | Priority |
|------|---------|----------|
| `README.md` | Project overview | Day 1 |
| `CONTRIBUTING.md` | Contribution guidelines | Day 1 |
| `src/Api/Program.cs` | API entry point | Week 1 |
| `src/SharedKernel/Domain/` | Domain models | Week 1 |
| `docs/architecture/` | Architecture docs | Week 1 |
### Code Conventions
**Naming:**
- Classes: `PascalCase`
- Methods: `PascalCase`
- Variables: `camelCase`
- Constants: `UPPER_SNAKE_CASE`
- Files: Match class name
**Project Structure:**
- Vertical slice architecture
- Feature folders over layer folders
- One class per file (with exceptions for records)
---
## Development Workflow
### Git Workflow
```text
main ────────────────────────────────────────────────────────►
│ │
└── feature/ABC-123-add-user-auth ─────────┘
│ │ │
▼ ▼ ▼
commit commit commit
```
**Branch Naming:**
- `feature/TICKET-description` - New features
- `fix/TICKET-description` - Bug fixes
- `chore/description` - Maintenance tasks
**Commit Messages:**
```text
type(scope): description
feat(auth): add OAuth2 support for Azure AD
fix(api): resolve null reference in user service
docs(readme): update installation instructions
```
### Code Review Process
1. Create feature branch from `main`
2. Make changes with meaningful commits
3. Push and create pull request
4. Request review from team member
5. Address feedback
6. Merge when approved (squash merge)
### Testing Requirements
- All new code must have tests
- Minimum 80% code coverage for new features
- Integration tests for API endpoints
- E2E tests for critical user flows
```bash
# Run all tests
dotnet test
# Run with coverage
dotnet test --collect:"XPlat Code Coverage"
# Run specific test project
dotnet test tests/Unit/
```
---
## Common Tasks
### Adding a New API Endpoint
1. Create feature folder in `src/Api/Features/`
2. Add request/response models
3. Implement endpoint handler
4. Add validation
5. Write tests
6. Update OpenAPI documentation
**Example:**
```csharp
// src/Api/Features/Users/GetUser.cs
public static class GetUser
{
public sealed record Response(Guid Id, string Name, string Email);
public static void Map(IEndpointRouteBuilder app) =>
app.MapGet("/api/users/{id:guid}", HandleAsync)
.WithName("GetUser")
.WithTags("Users")
.Produces<Response>()
.ProducesProblem(StatusCodes.Status404NotFound);
private static async Task<IResult> HandleAsync(
Guid id,
IUserRepository repository,
CancellationToken ct)
{
var user = await repository.GetByIdAsync(id, ct);
return user is null
? Results.NotFound()
: Results.Ok(new Response(user.Id, user.Name, user.Email));
}
}
```
### Running Database Migrations
```bash
# Add a new migration
dotnet ef migrations add AddUserTable -p src/Api -s src/Api
# Apply migrations
dotnet ef database update -p src/Api -s src/Api
# Generate SQL script
dotnet ef migrations script -p src/Api -s src/Api -o migration.sql
```
### Debugging
**VS Code:**
1. Set breakpoint (F9)
2. Start debugging (F5)
3. Use debug console for evaluation
**Rider:**
1. Set breakpoint
2. Debug (Shift+F9)
3. Use Evaluate Expression
**Logging:**
```csharp
_logger.LogInformation("Processing request {RequestId}", requestId);
_logger.LogError(exception, "Failed to process {RequestId}", requestId);
```
---
## Learning Path
### Week 1: Foundations
| Day | Topic | Resources |
|-----|-------|-----------|
| 1 | Environment setup | This guide |
| 2 | Architecture overview | `/docs/architecture/` |
| 3 | Codebase walkthrough | Pair with buddy |
| 4 | First bug fix | Assigned starter issue |
| 5 | Code review | Review teammate's PR |
### Week 2-4: Building Competence
- [ ] Complete a small feature end-to-end
- [ ] Write integration tests
- [ ] Participate in sprint planning
- [ ] Present at team standup
- [ ] Shadow on-call rotation
### Month 2-3: Independence
- [ ] Own a medium-sized feature
- [ ] Mentor newer team members
- [ ] Contribute to documentation
- [ ] Join on-call rotation
- [ ] Present technical topic to team
---
## Getting Help
### Onboarding Buddy
Your onboarding buddy is: **[Name]**
- Slack: @[handle]
- Email: [email]
They're your first point of contact for questions!
### Team Channels
| Channel | Purpose |
|---------|---------|
| #team-[name] | General team discussion |
| #team-[name]-dev | Technical questions |
| #incidents | Production issues |
| #random | Non-work chat |
### Escalation
If you're blocked:
1. **Try self-service first**: Search docs, Slack history, Stack Overflow
2. **Ask in team channel**: Others may have same question
3. **Direct message buddy**: For quick questions
4. **Schedule 1:1**: For longer discussions
---
## FAQ
**Q: How do I get access to [system]?**
A: Request in #access-requests channel with your manager's approval.
**Q: Where do I find [documentation]?**
A: Start at [docs-site-url]. Use search or ask in #team-dev.
**Q: What should I do if tests fail on CI?**
A: Check the CI logs first. If unclear, ask in #team-dev with a link to the failed build.
**Q: How do I deploy to staging?**
A: Merging to `main` auto-deploys to staging. Check #deployments channel.
---
## Feedback
We continuously improve our onboarding process. Please share your experience:
- What worked well?
- What was confusing?
- What was missing?
Send feedback to: [email/form/channel]
---
**Next Review:** [Date]
Learning Path Template
# Learning Path: [Role/Technology]
## Overview
This learning path helps you become proficient in [topic].
**Estimated Duration:** [X] weeks
**Prerequisites:** [List]
---
## Level 1: Fundamentals (Week 1)
### Goals
- [ ] Understand core concepts
- [ ] Set up development environment
- [ ] Complete "Hello World" tutorial
### Resources
| Type | Resource | Time |
|------|----------|------|
| Video | [Introduction to X] | 30 min |
| Tutorial | [Getting Started] | 2 hours |
| Documentation | [Core Concepts] | 1 hour |
### Exercises
1. [Exercise 1]
2. [Exercise 2]
### Checkpoint
- Can you explain [concept] in your own words?
- Have you built [artifact]?
---
## Level 2: Intermediate (Weeks 2-3)
### Goals
- [ ] Build a complete feature
- [ ] Understand [advanced topic]
- [ ] Write tests
### Resources
| Type | Resource | Time |
|------|----------|------|
| Course | [Deep Dive into X] | 4 hours |
| Book | [Recommended Reading] Chapter 1-5 | 3 hours |
| Practice | [Hands-on Lab] | 2 hours |
### Project
Build [project description] that demonstrates:
- [Skill 1]
- [Skill 2]
- [Skill 3]
### Checkpoint
- Can you [task] without referring to documentation?
- Have you completed the [project]?
---
## Level 3: Advanced (Weeks 4+)
### Goals
- [ ] Optimize for performance
- [ ] Handle edge cases
- [ ] Mentor others
### Resources
| Type | Resource | Time |
|------|----------|------|
| Advanced | [Performance Optimization] | 2 hours |
| Case Study | [Real-world Examples] | 1 hour |
| Community | [Contribute to OSS] | Ongoing |
### Milestone
You've reached proficiency when you can:
- [ ] Design solutions independently
- [ ] Review others' code confidently
- [ ] Explain trade-offs to stakeholders
Best Practices
Content Principles
| Principle | Description |
|---|---|
| Progressive | Start simple, increase complexity |
| Practical | Focus on doing, not just reading |
| Current | Keep up-to-date with system changes |
| Accessible | Easy to find and navigate |
| Feedback-driven | Iterate based on new hire input |
Anti-Patterns to Avoid
- Overwhelming Day 1 with too much information
- Assuming prior knowledge without verification
- Outdated setup instructions
- No checkpoint/verification steps
- Missing "getting help" information
Workflow
When creating onboarding docs:
- Audit Current State: What exists? What's outdated?
- Interview Recent Hires: What was confusing? Missing?
- Define Learning Goals: What should they know at each stage?
- Create Progressive Content: Day 1 → Week 1 → Month 1
- Add Verification Steps: How do they know they succeeded?
- Test with Real User: Have someone follow the guide
- Iterate: Update based on feedback
References
For detailed guidance:
Last Updated: 2025-12-26