Documentation is the guidebook for your codebase. It answers questions before they’re asked, reduces onboarding time, and helps everyone understand why decisions were made. But documentation doesn’t need to be overwhelming — a few strategic documents go a long way.

• Reduces interruptions: Well-documented projects get fewer “how does this work?” questions
• Preserves knowledge: Team members leave, but documentation stays
• Speeds up onboarding: New developers can ramp up faster
• Prevents mistakes: Clear setup docs reduce configuration errors

Documentation is like a recipe book. You don’t need a novel for every dish — just clear steps, accurate measurements, and a photo of the finished result. The best recipes are the ones that work the first time.

Every project needs a README. Keep it short and focused.

# Project Name

Brief description of what the project does.

## Tech Stack

- Next.js 14 (App Router)
- TypeScript
- Prisma (PostgreSQL)
- Auth.js

## Getting Started

\`\`\`bash
git clone https://github.com/org/project
cd project
npm install
cp .env.example .env
npm run dev
\`\`\`

## Project Structure

A quick overview of the main directories.

Document environment setup for new developers.

## Environment Setup

1. Copy \`.env.example\` to \`.env\`
2. Get API keys from:
   - Database: [Vercel Postgres Dashboard](https://vercel.com/dashboard)
   - Auth: [GitHub OAuth App](https://github.com/settings/developers)
3. Run database migrations: \`npx prisma migrate dev\`
4. Seed sample data: \`npx prisma db seed\`

For significant decisions, document why you chose one approach over another.

# ADR-001: Use Auth.js for Authentication

## Context
We needed authentication with Google and GitHub login, session management, and middleware route protection.

## Decision
Use Auth.js (next-auth) because:
- Built-in support for OAuth providers
- Works with Server Components and Middleware
- Active maintenance and community

## Alternatives Considered
- Clerk: Excellent DX but vendor lock-in
- Supabase Auth: Good if already using Supabase
- Custom Auth: Too much maintenance for our team size

## Status
Accepted

For reusable components, document props and usage.

/**
 * Avatar component with fallback initials.
 *
 * @example
 * <Avatar name="John Doe" image="/photos/john.jpg" size="lg" />
 *
 * @param {string} name - Display name (initials shown when no image)
 * @param {string} [image] - Optional image URL
 * @param {'sm' | 'md' | 'lg'} [size='md'] - Avatar size
 */
export function Avatar({ name, image, size = 'md' }: AvatarProps) {
  // ...
}

Document common operational tasks.

## Runbook

### Deploy a hotfix
1. Create a branch from main
2. Fix the issue
3. Get a code review
4. Merge and deploy

### Roll back a deployment
1. Go to Vercel dashboard
2. Select the deployment
3. Click "Promote to Production" on the previous version

### Clear Redis cache
\`\`\`bash
redis-cli FLUSHALL
\`\`\`

• Keep documentation close to the code (in the same repo)
• Update docs when you make changes — stale docs are worse than no docs
• Use examples over long explanations
• Write for the newest team member — they’ll thank you
• Use // TODO: update docs as a reminder when you skip documentation in a PR
• Document why, not what — the code already shows what

• Documentation rot: Not updating docs when code changes
• Over-documenting: Writing a novel for a simple utility function
• Assuming knowledge: Skipping basics that new team members need
• Scattered docs: Information spread across README, wiki, Notion, and Slack with no single source of truth

Good documentation doesn’t need to be comprehensive — it needs to be accurate, findable, and maintained. A short README, component-level comments, and a few ADRs for major decisions will cover 90% of what your team needs.

• Clean Code
• Code Review
• Project Checklist