Documentation Best Practices: Comprehensive Guide

# Project Name

Brief description of what this project does.

## Features

- Feature 1
- Feature 2
- Feature 3

## Quick Start

```bash
npm install my-project
npm start

npm install my-project

import { myFunction } from 'my-project';

const result = myFunction('hello');
console.log(result);

<Button variant="primary">Primary</Button>

<Button variant="secondary">Secondary</Button>

# Architectural Decision Records (ADR)

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| 001 | Use PostgreSQL | Accepted | 2024-01-15 |
| 002 | Use React | Accepted | 2024-01-20 |
| 003 | Use GraphQL | Proposed | 2024-02-01 |
| 004 | Use AWS | Accepted | 2024-02-05 |

// Calculate discount based on user tier
// Users with 10+ orders get 20% off
function calculateDiscount(user) {
  if (user.orderCount >= 10) {
    return 0.20;
  }
  return 0;
}

// Handle API rate limiting
// Exponential backoff: 1s, 2s, 4s, 8s...
async function fetchWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fetch(url);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000);
    }
  }
}

/**
 * Calculates the total price including tax and discounts.
 *
 * @param {number} basePrice - The original price before tax/discount
 * @param {Object} options - Calculation options
 * @param {number} options.taxRate - Tax rate as decimal (0.1 = 10%)
 * @param {number} [options.discount=0] - Discount as decimal
 * @returns {number} Final calculated price
 *
 * @example
 * calculateTotal(100, { taxRate: 0.1, discount: 0.1 }); // 99
 *
 * @since 1.2.0
 * @deprecated Use calculatePrice instead
 */
function calculateTotal(basePrice, options) {
  const { taxRate, discount = 0 } = options;
  return basePrice * (1 + taxRate) * (1 - discount);
}

interface User {
  /** Unique identifier */
  id: string;
  
  /** User's display name */
  name: string;
  
  /** Email address */
  email: string;
  
  /** When user was created */
  readonly createdAt: Date;
}

/**
 * Creates a new user in the system.
 * 
 * @param data - User creation data
 * @returns Created user with generated ID
 * @throws {ValidationError} When data is invalid
 * 
 * @example
 * const user = await createUser({
 *   name: 'John',
 *   email: '[email protected]'
 * });
 */
async function createUser(data: CreateUserInput): Promise<User>

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0

paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email

nav:
  - Home: index.md
  - Getting Started:
      - Installation: getting-started/installation.md
      - Quick Start: getting-started/quick-start.md
  - Guides:
      - Authentication: guides/authentication.md
      - Deployment: guides/deployment.md
  - API Reference:
      - Users: api/users.md
  - CLI:
      - Commands: reference/cli-commands.md

<!-- Bad -->
The functionality of this method is to iterate through the array and return the first element that matches the predicate.

<!-- Good -->
Returns the first array element that matches the predicate.

<!-- Good with example -->
To create a user:

```javascript
const user = await createUser({
  name: 'John',
  email: 'john@example.com'
});

<!-- Good -->
Use `process.env.NODE_ENV` to check the environment:

- `development`: Local development
- `staging`: Testing environment  
- `production`: Live environment

// jsdoc.json
{
  "source": {
    "include": ["src"]
  },
  "opts": {
    "destination": "./docs",
    "template": "node_modules/docdash"
  },
  "plugins": ["plugins/markdown"]
}

## Documentation Review

- [ ] All public APIs documented
- [ ] Code examples tested
- [ ] Links work
- [ ] Spelling/grammar correct
- [ ] Diagrams up-to-date
- [ ] Version numbers current
- [ ] Examples run without errors

# .github/workflows/docs.yml
name: Documentation

on:
  push:
    branches: [main]
    paths: ['docs/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force