Onboarding Helper Skill
Generate comprehensive onboarding documentation and guides for new developers joining your team or project.
Instructions
You are an onboarding and developer experience expert. When invoked:
- •
Assess Onboarding Needs:
- •Project complexity and technology stack
- •Team size and structure
- •Development workflow and processes
- •Domain knowledge requirements
- •Common onboarding challenges
- •
Create Onboarding Materials:
- •Welcome documentation
- •Development environment setup guides
- •Codebase architecture overview
- •First-task tutorials
- •Team processes and conventions
- •
Organize Learning Path:
- •Day 1, Week 1, Month 1 goals
- •Progressive complexity
- •Hands-on exercises
- •Checkpoint milestones
- •Resources and references
- •
Document Team Culture:
- •Communication channels
- •Meeting schedules
- •Code review practices
- •Decision-making processes
- •Team values and norms
- •
Enable Self-Service:
- •FAQ sections
- •Troubleshooting guides
- •Links to resources
- •Who to ask for what
- •Common gotchas
Onboarding Documentation Structure
Complete Onboarding Guide Template
# Welcome to [Project Name]! 👋 Welcome! We're excited to have you on the team. This guide will help you get up to speed quickly and smoothly. ## Table of Contents 1. [Overview](#overview) 2. [Day 1: Getting Started](#day-1-getting-started) 3. [Week 1: Core Concepts](#week-1-core-concepts) 4. [Month 1: Making Impact](#month-1-making-impact) 5. [Team & Processes](#team--processes) 6. [Resources](#resources) 7. [FAQ](#faq) --- ## Overview ### What We're Building We're building a modern e-commerce platform that helps small businesses sell online. Our platform handles: - Product catalog management - Shopping cart and checkout - Payment processing (Stripe integration) - Order fulfillment and tracking - Customer relationship management **Our Mission**: Make e-commerce accessible to businesses of all sizes. **Our Users**: Small to medium business owners with 10-1000 products. ### Technology Stack **Frontend**: - React 18 with TypeScript - Redux Toolkit for state management - Material-UI component library - React Query for API calls - Vite for build tooling **Backend**: - Node.js with Express - PostgreSQL database - Redis for caching - Stripe for payments - AWS S3 for file storage **Infrastructure**: - Docker for local development - Kubernetes for production - GitHub Actions for CI/CD - AWS (EC2, RDS, S3, CloudFront) - DataDog for monitoring ### Project Statistics - **Started**: January 2023 - **Team Size**: 12 engineers (4 frontend, 5 backend, 3 full-stack) - **Codebase**: ~150K lines of code - **Active Users**: 5,000+ businesses - **Monthly Transactions**: $2M+ --- ## Day 1: Getting Started ### Your First Day Checklist - [ ] Complete HR onboarding - [ ] Get added to communication channels - [ ] Set up development environment - [ ] Clone the repository - [ ] Run the application locally - [ ] Deploy to your personal dev environment - [ ] Introduce yourself to the team - [ ] Schedule 1:1s with your manager and buddy ### Access & Accounts **Required Accounts**: 1. **GitHub** - Source code ([github.com/company/project](https://github.com)) - Request access from @engineering-manager 2. **Slack** - Team communication - Channels: #engineering, #frontend, #backend, #general 3. **Jira** - Project management ([company.atlassian.net](https://company.atlassian.net)) 4. **Figma** - Design files 5. **AWS Console** - Production access (read-only initially) 6. **DataDog** - Monitoring and logs **Development Tools**: - Docker Desktop - Node.js 18+ (use nvm) - PostgreSQL client (psql or pgAdmin) - Postman or Insomnia (API testing) - VS Code (recommended, see extensions below) ### Environment Setup #### 1. Install Prerequisites **macOS**: ```bash # Install Homebrew /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # Install Node.js via nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash nvm install 18 nvm use 18 # Install Docker Desktop brew install --cask docker # Install PostgreSQL client brew install postgresql@14
Windows:
# Install using Chocolatey choco install nodejs-lts docker-desktop postgresql14
2. Clone Repository
# Clone the repo git clone git@github.com:company/ecommerce-platform.git cd ecommerce-platform # Install dependencies npm install # Copy environment variables cp .env.example .env.local
3. Configure Environment Variables
Edit .env.local:
# Database (local Docker) DATABASE_URL=postgresql://postgres:password@localhost:5432/ecommerce_dev # Redis REDIS_URL=redis://localhost:6379 # Stripe (use test keys) STRIPE_SECRET_KEY=sk_test_... # Get from @backend-lead STRIPE_PUBLISHABLE_KEY=pk_test_... # AWS S3 (dev bucket) AWS_ACCESS_KEY_ID=... # Get from @devops AWS_SECRET_ACCESS_KEY=... AWS_S3_BUCKET=ecommerce-dev-uploads # Session SESSION_SECRET=your-random-secret-here
Where to get credentials:
- •Stripe test keys: 1Password vault "Development Secrets"
- •AWS credentials: Request from @devops in #engineering
- •Session secret: Generate with
openssl rand -base64 32
4. Start Development Environment
# Start Docker services (PostgreSQL, Redis) docker-compose up -d # Run database migrations npm run db:migrate # Seed database with sample data npm run db:seed # Start development server npm run dev
Expected output:
✔ Database migrated successfully ✔ Seeded 100 products, 50 users ✔ Server running on http://localhost:3000 ✔ API available at http://localhost:3000/api
5. Verify Installation
Open your browser to http://localhost:3000
You should see the application home page with sample products.
Test credentials:
- •Email:
test@example.com - •Password:
password123
Troubleshooting:
- •Port 3000 in use: Kill the process with
lsof -ti:3000 | xargs kill -9 - •Database connection failed: Check Docker is running with
docker ps - •Module not found: Delete
node_modulesand runnpm installagain
See Troubleshooting Guide for more help.
VS Code Setup
Recommended Extensions:
{
"recommendations": [
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode",
"bradlc.vscode-tailwindcss",
"ms-azuretools.vscode-docker",
"eamodio.gitlens",
"orta.vscode-jest",
"prisma.prisma"
]
}
Settings (.vscode/settings.json):
{
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true
},
"typescript.tsdk": "node_modules/typescript/lib"
}
Your First Commit
Let's make a simple change to verify your setup:
- •
Create a branch:
bashgit checkout -b test/your-name-setup
- •
Add your name to the team page: Edit
src/pages/About.tsx:typescriptconst teamMembers = [ // ... existing members { name: 'Your Name', role: 'Software Engineer', joinedDate: '2024-01-15' } ]; - •
Test your change:
bashnpm run test npm run lint
- •
Commit and push:
bashgit add . git commit -m "docs: Add [Your Name] to team page" git push origin test/your-name-setup
- •
Create a PR:
- •Go to GitHub
- •Click "Compare & pull request"
- •Fill out the PR template
- •Request review from your buddy
Congrats on your first contribution! 🎉
End of Day 1
You should now have:
- •✅ Development environment running locally
- •✅ Application accessible in your browser
- •✅ First PR created
- •✅ Access to all team tools and channels
Questions? Ask in #engineering or DM your buddy!
Week 1: Core Concepts
Project Architecture
High-Level Architecture
┌─────────────┐
│ Browser │
│ (React) │
└──────┬──────┘
│ HTTPS
▼
┌─────────────┐ ┌──────────────┐
│ API Gateway │────▶│ Auth Service│
│ (Express) │ │ (JWT) │
└──────┬──────┘ └──────────────┘
│
├────▶ Product Service
│
├────▶ Order Service
│
├────▶ Payment Service ────▶ Stripe API
│
└────▶ User Service
│
▼
┌──────────┐
│PostgreSQL│
└──────────┘
Directory Structure
ecommerce-platform/ ├── client/ # Frontend React app │ ├── src/ │ │ ├── components/ # Reusable UI components │ │ ├── pages/ # Page components │ │ ├── hooks/ # Custom React hooks │ │ ├── store/ # Redux store and slices │ │ ├── api/ # API client functions │ │ ├── utils/ # Utility functions │ │ └── types/ # TypeScript type definitions │ └── tests/ # Frontend tests │ ├── server/ # Backend Node.js app │ ├── src/ │ │ ├── routes/ # Express route handlers │ │ ├── controllers/ # Business logic │ │ ├── services/ # External integrations │ │ ├── models/ # Database models (Prisma) │ │ ├── middleware/ # Express middleware │ │ ├── utils/ # Utility functions │ │ └── types/ # TypeScript types │ └── tests/ # Backend tests │ ├── docs/ # Documentation ├── scripts/ # Build and deployment scripts ├── .github/ # GitHub Actions workflows └── docker-compose.yml # Local development services
Key Concepts
1. Authentication Flow
// User logs in
POST /api/auth/login
{ email, password }
↓
// Server validates credentials
// Generates JWT token
↓
// Client stores token
localStorage.setItem('token', token)
↓
// Client includes token in requests
Authorization: Bearer <token>
↓
// Server validates token
// Attaches user to request
req.user = decodedToken
Code location: server/src/middleware/auth.ts
2. State Management (Redux)
We use Redux Toolkit for client-side state:
// Store structure
{
auth: {
user: User | null,
isAuthenticated: boolean,
loading: boolean
},
cart: {
items: CartItem[],
total: number
},
products: {
list: Product[],
filters: FilterState,
loading: boolean
}
}
Reading from store:
import { useAppSelector } from '@/hooks/redux';
const user = useAppSelector(state => state.auth.user);
const cartItems = useAppSelector(state => state.cart.items);
Dispatching actions:
import { useAppDispatch } from '@/hooks/redux';
import { addToCart } from '@/store/slices/cartSlice';
const dispatch = useAppDispatch();
dispatch(addToCart({ productId, quantity: 1 }));
Code location: client/src/store/
3. API Communication
We use React Query for server state:
import { useQuery, useMutation } from '@tanstack/react-query';
import { api } from '@/api/client';
// Fetching data
const { data, isLoading, error } = useQuery({
queryKey: ['products'],
queryFn: () => api.products.getAll()
});
// Mutating data
const mutation = useMutation({
mutationFn: (product) => api.products.create(product),
onSuccess: () => {
queryClient.invalidateQueries(['products']);
}
});
Code location: client/src/api/
4. Database Access (Prisma)
We use Prisma ORM for database operations:
import { prisma } from '@/lib/prisma';
// Find one
const user = await prisma.user.findUnique({
where: { id: userId }
});
// Find many with filters
const products = await prisma.product.findMany({
where: {
category: 'electronics',
price: { lt: 1000 }
},
include: {
images: true,
reviews: true
}
});
// Create
const order = await prisma.order.create({
data: {
userId,
total: 100,
items: {
create: [
{ productId: 1, quantity: 2, price: 50 }
]
}
}
});
Code location: server/src/models/
Schema: prisma/schema.prisma
Your First Real Task
Goal: Add a "Recently Viewed" feature to product pages.
Requirements:
- •Track products a user views
- •Display last 5 viewed products
- •Persist across sessions (use localStorage)
- •Show on product detail page
Steps:
- •
Create a feature branch:
bashgit checkout -b feature/recently-viewed-products
- •
Frontend: Add hook (
client/src/hooks/useRecentlyViewed.ts):typescriptexport function useRecentlyViewed() { const addToRecentlyViewed = (product: Product) => { // Get existing const recent = JSON.parse(localStorage.getItem('recentlyViewed') || '[]'); // Add new (avoid duplicates) const updated = [ product, ...recent.filter((p: Product) => p.id !== product.id) ].slice(0, 5); // Save localStorage.setItem('recentlyViewed', JSON.stringify(updated)); }; const getRecentlyViewed = (): Product[] => { return JSON.parse(localStorage.getItem('recentlyViewed') || '[]'); }; return { addToRecentlyViewed, getRecentlyViewed }; } - •
Frontend: Use in product page (
client/src/pages/ProductDetail.tsx):typescriptconst { addToRecentlyViewed, getRecentlyViewed } = useRecentlyViewed(); useEffect(() => { if (product) { addToRecentlyViewed(product); } }, [product]); const recentProducts = getRecentlyViewed(); - •
Frontend: Display component (
client/src/components/RecentlyViewed.tsx):typescriptexport function RecentlyViewed({ currentProductId }: Props) { const { getRecentlyViewed } = useRecentlyViewed(); const products = getRecentlyViewed() .filter(p => p.id !== currentProductId); if (products.length === 0) return null; return ( <section> <h2>Recently Viewed</h2> <ProductGrid products={products} /> </section> ); } - •
Add tests:
typescriptdescribe('useRecentlyViewed', () => { it('should add product to recently viewed', () => { const { addToRecentlyViewed, getRecentlyViewed } = useRecentlyViewed(); addToRecentlyViewed(mockProduct); expect(getRecentlyViewed()).toContainEqual(mockProduct); }); it('should limit to 5 products', () => { // Add 6 products, check only 5 remain }); it('should move duplicate to front', () => { // Add same product twice, check it appears once at front }); }); - •
Test manually:
- •View several products
- •Check localStorage in DevTools
- •Verify list appears on product pages
- •Test edge cases (empty state, single item)
- •
Create PR:
- •Use PR template
- •Add screenshots
- •Request review from @frontend-team
Resources:
Week 1 Learning Resources
Must Read:
Optional Deep Dives:
End of Week 1
You should now:
- •✅ Understand overall architecture
- •✅ Know key technologies and tools
- •✅ Have completed your first feature
- •✅ Understand our development workflow
- •✅ Feel comfortable asking questions
Checkpoint Meeting: Schedule 30min with your manager to review progress.
Month 1: Making Impact
Month 1 Goals
- •Ship Features: Complete 3-5 features independently
- •Code Reviews: Provide meaningful feedback on 10+ PRs
- •Fix Bugs: Tackle 2-3 bug fixes
- •Improve Something: Find and fix a small pain point
- •Learn Domain: Understand e-commerce business basics
Suggested Feature Ideas
Beginner Friendly:
- •Add product sorting (price, rating, newest)
- •Implement wishlist functionality
- •Create order history page
- •Add email notifications
Intermediate:
- •Implement product reviews and ratings
- •Add search autocomplete
- •Create admin dashboard for orders
- •Optimize image loading performance
Advanced:
- •Implement shopping cart abandonment recovery
- •Add real-time inventory tracking
- •Create recommendation engine
- •Set up A/B testing framework
Finding Tasks: Check Jira board for issues labeled good-first-issue.
Code Review Best Practices
As an Author:
- •Keep PRs small (< 400 lines changed)
- •Write clear descriptions
- •Add screenshots for UI changes
- •Respond to feedback promptly
- •Test thoroughly before requesting review
As a Reviewer:
- •Review within 24 hours
- •Be kind and constructive
- •Ask questions rather than demand changes
- •Highlight good practices
- •Approve when ready (don't nitpick)
Review Checklist:
- • Code follows style guide
- • Tests included and passing
- • No console.logs in production code
- • Error handling implemented
- • Performance considerations addressed
- • Security best practices followed
Resources: Code Review Guide
Testing Guidelines
What to Test:
- •Business logic (always)
- •User interactions (important flows)
- •Edge cases and error states
- •API integrations (with mocks)
Testing Pyramid:
/\
/ \ E2E Tests (few)
/────\
/ \ Integration Tests (some)
/────────\
/ \ Unit Tests (many)
/────────────\
Running Tests:
# All tests npm test # Watch mode npm test -- --watch # Coverage npm test -- --coverage # Specific file npm test UserService.test.ts
Writing Tests:
describe('CartService', () => {
describe('addToCart', () => {
it('should add item to empty cart', () => {
// Arrange
const cart = new Cart();
const item = { productId: 1, quantity: 2 };
// Act
cart.addItem(item);
// Assert
expect(cart.items).toHaveLength(1);
expect(cart.items[0]).toEqual(item);
});
it('should increase quantity if item exists', () => {
// Test implementation
});
it('should throw error if quantity is negative', () => {
// Test implementation
});
});
});
Resources: Testing Guide
Deployment Process
Environments:
- •Development: Your local machine
- •Staging: https://staging.ecommerce.example.com
- •Production: https://ecommerce.example.com
Deployment Flow:
main branch
│
▼
CI runs (tests, lint, build)
│
▼
Auto-deploy to Staging
│
▼
Manual QA testing
│
▼
Create release tag
│
▼
Deploy to Production (gradual rollout)
You can deploy: Staging (automatic on merge to main) You cannot deploy: Production (requires approval)
Monitoring:
- •Logs: DataDog dashboard
- •Errors: Sentry alerts
- •Metrics: Custom dashboards
Team & Processes
Team Structure
Engineering Team:
- •Engineering Manager: @alice (1:1s, career growth)
- •Tech Lead: @bob (architecture decisions, technical direction)
- •Frontend Team (4 engineers): @carol, @dave, @eve, @frank
- •Backend Team (5 engineers): @grace, @henry, @ivy, @jack, @kate
- •Full-Stack (3 engineers): @liam, @maya, @noah
Adjacent Teams:
- •Product: @olivia (product manager)
- •Design: @peter, @quinn (UI/UX designers)
- •QA: @rachel, @sam (test engineers)
- •DevOps: @taylor (infrastructure)
Communication Channels
Slack Channels:
- •
#engineering- General engineering discussions - •
#frontend- Frontend-specific topics - •
#backend- Backend-specific topics - •
#deploys- Deployment notifications - •
#incidents- Production issues - •
#random- Non-work chat
When to use what:
- •Slack: Quick questions, discussions, FYIs
- •Jira: Task tracking, bug reports
- •GitHub: Code discussions, PR reviews
- •Email: External communication, formal notices
- •Zoom: Meetings, pair programming, deep discussions
Meetings
Weekly:
- •Team Standup (Mon/Wed/Fri, 10am, 15min)
- •What you did
- •What you're doing
- •Any blockers
- •Sprint Planning (Monday, 1pm, 1hr)
- •Plan next sprint
- •Estimate stories
- •Retro (Friday, 2pm, 45min)
- •What went well
- •What could improve
- •Action items
Bi-weekly:
- •1:1 with Manager (30min)
- •Career growth
- •Feedback
- •Questions
Monthly:
- •All-Hands (First Friday, 3pm, 1hr)
- •Company updates
- •Team showcases
Meeting Norms:
- •Cameras on when possible
- •Mute when not speaking
- •Be on time
- •Come prepared
- •Take notes
Development Workflow
Git Workflow:
main (protected) ├─ feature/add-wishlist ├─ fix/cart-bug └─ refactor/payment-service
Branch Naming:
- •
feature/description- New features - •
fix/description- Bug fixes - •
refactor/description- Code refactoring - •
docs/description- Documentation - •
test/description- Tests only
Commit Messages:
type(scope): description feat(cart): add wishlist functionality fix(auth): resolve token expiration issue docs(readme): update setup instructions test(orders): add integration tests refactor(database): optimize queries
PR Process:
- •Create feature branch
- •Make changes
- •Write tests
- •Create PR (use template)
- •Request review (minimum 1 approval)
- •Address feedback
- •Merge (squash and merge)
On-Call Rotation
You won't be on-call for your first 3 months.
When you join rotation:
- •1 week on-call per month
- •Respond to PagerDuty alerts
- •Fix production issues
- •Escalate if needed
Resources: On-Call Runbook
Resources
Documentation
- •README - Project overview
- •Architecture - System design
- •API Docs - API reference
- •Contributing - How to contribute
- •Style Guide - Code conventions
- •Testing Guide - Testing practices
- •Deployment - Deployment process
- •Troubleshooting - Common issues
Learning Resources
JavaScript/TypeScript:
React:
Node.js:
Databases:
System Design:
Internal Tools
- •1Password: Shared credentials
- •Notion: Team wiki and docs
- •Figma: Design files
- •DataDog: Monitoring and logs
- •Sentry: Error tracking
- •GitHub: Code repository
- •Jira: Project management
Your Buddy
Your onboarding buddy is @buddy-name.
Your buddy will:
- •Answer day-to-day questions
- •Review your first few PRs
- •Introduce you to the team
- •Help you navigate processes
- •Meet with you weekly (first month)
Don't hesitate to ask them anything!
FAQ
Development
Q: How do I reset my local database?
npm run db:reset # Drops all data and re-runs migrations npm run db:seed # Adds sample data
Q: Tests are failing locally but passing in CI. Why?
- •Check Node version matches (use
nvm use) - •Clear
node_modulesand reinstall - •Check for environment-specific tests
Q: How do I debug the backend?
Add debugger; statement and run:
node --inspect-brk server/src/index.ts
Then open Chrome DevTools.
Q: Where do I find API credentials for development? Check 1Password vault "Development Secrets" or ask in #engineering.
Code & Practices
Q: When should I create a new component vs. modify existing?
- •Create new: Reusable, self-contained functionality
- •Modify existing: Extending current component's capabilities
- •When in doubt, ask in PR review
Q: How much test coverage is expected?
- •Aim for 80% overall
- •100% for business-critical logic (payments, auth)
- •Focus on valuable tests, not just coverage numbers
Q: Can I refactor code I'm working on? Yes, but:
- •Keep refactoring in separate commits
- •Don't mix feature work with large refactors
- •For big refactors, create separate PR
Q: What if I disagree with PR feedback?
- •Discuss politely in PR comments
- •Explain your reasoning
- •Escalate to tech lead if needed
- •Remember: we're all learning
Process
Q: How do I report a production bug?
- •Post in #incidents with details
- •Create Jira ticket (type: Bug, priority: based on severity)
- •If urgent, ping on-call engineer
Q: Can I work on something not in Jira?
- •Small improvements: Yes, create ticket after
- •Large projects: Check with manager first
- •Tech debt: Discuss in sprint planning
Q: How do I request time off?
- •Add to team calendar
- •Message manager on Slack
- •Update Jira board if you have active work
Q: I'm stuck on a problem for hours. What should I do?
- •Try debugging and Googling (30 min)
- •Ask in #engineering (don't struggle alone)
- •Schedule pairing session with teammate
- •Escalate to tech lead if still stuck
Rule of thumb: Ask for help after 30 minutes of being stuck.
Career & Growth
Q: How is performance evaluated?
- •Quarterly reviews with manager
- •Based on: code quality, velocity, collaboration, growth
- •Transparent rubric provided
Q: How do I learn more about [specific topic]?
- •Ask in #engineering for recommendations
- •Check internal wiki for resources
- •Request Udemy/book budget from manager
Q: Can I switch teams/projects?
- •Discuss with manager after 6 months
- •Internal mobility encouraged
Welcome Aboard!
Remember:
- •Ask Questions: No question is too small
- •Take Breaks: Onboarding is exhausting
- •Be Patient: It takes 3+ months to feel productive
- •Have Fun: We're building something cool together!
Need help? Your buddy (@buddy-name) and manager (@manager-name) are here for you.
Welcome to the team! 🚀
## Usage Examples
@onboarding-helper @onboarding-helper --type full-guide @onboarding-helper --type quick-start @onboarding-helper --type architecture-overview @onboarding-helper --focus frontend @onboarding-helper --include-exercises
## Best Practices ### Make It Personal - Address new team member by name - Assign a buddy/mentor - Include team photos and bios - Share team culture and values ### Progressive Disclosure - Day 1: Just get running - Week 1: Understand basics - Month 1: Ship features - Month 3: Full productivity ### Make It Interactive - Include hands-on exercises - Provide starter tasks - Encourage pair programming - Set up regular check-ins ### Keep It Updated - Review quarterly - Get feedback from new hires - Update for tech stack changes - Improve based on common questions ### Make It Discoverable - Central location (wiki, README) - Easy to navigate - Searchable - Version controlled ## Notes - Onboarding is an ongoing process, not a one-time event - Great onboarding significantly reduces time-to-productivity - Documentation should be discoverable and up-to-date - Assign mentors/buddies for personal guidance - Include both technical and cultural onboarding - Celebrate early wins to build confidence - Check in regularly during first 3 months - Encourage questions and create safe learning environment - Provide clear learning path with milestones - Make resources easily accessible - Update documentation based on new hire feedback