Documentation Writing

Core Principles

1. Audience-focused - Know who you're writing for
2. Task-oriented - Help users accomplish goals
3. Scannable - Use headers, lists, and code blocks
4. Accurate - Keep in sync with code
5. Complete - Cover common use cases and edge cases

README Structure

# Project Name

Brief description (1-2 sentences).

## Features

- Feature 1
- Feature 2

## Installation

npm install package-name

## Quick Start

import { thing } from 'package-name'; // Minimal working example

## Usage

### Basic Usage
Detailed examples with explanations.

### Advanced Usage
Complex scenarios and configuration.

## API Reference

Link to detailed docs or inline reference.

## Contributing

How to contribute to the project.

## License

MIT

JSDoc/TSDoc Comments

Functions

/**
 * Calculates the total price including tax.
 *
 * @param basePrice - The price before tax
 * @param taxRate - Tax rate as a decimal (e.g., 0.08 for 8%)
 * @returns The total price with tax applied
 *
 * @example
 * ```ts
 * const total = calculateTotal(100, 0.08);
 * // Returns: 108
 * ```
 *
 * @throws {RangeError} If taxRate is negative
 */
function calculateTotal(basePrice: number, taxRate: number): number {
  if (taxRate < 0) throw new RangeError('Tax rate cannot be negative');
  return basePrice * (1 + taxRate);
}

Classes

/**
 * Manages user authentication and session state.
 *
 * @remarks
 * This class handles OAuth2 authentication flows and maintains
 * session tokens in secure storage.
 *
 * @example
 * ```ts
 * const auth = new AuthManager({ clientId: 'xxx' });
 * await auth.login();
 * const user = auth.getCurrentUser();
 * ```
 */
class AuthManager {
  /**
   * Creates a new AuthManager instance.
   * @param config - Authentication configuration options
   */
  constructor(config: AuthConfig) {}

  /**
   * Initiates the login flow.
   * @returns Promise that resolves when authentication completes
   */
  async login(): Promise<void> {}
}

Interfaces

/**
 * Configuration options for the API client.
 */
interface ApiClientConfig {
  /**
   * Base URL for all API requests.
   * @example "https://api.example.com/v1"
   */
  baseUrl: string;

  /**
   * Request timeout in milliseconds.
   * @default 30000
   */
  timeout?: number;

  /**
   * Custom headers to include in all requests.
   */
  headers?: Record<string, string>;
}

API Documentation

OpenAPI/Swagger

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0
  description: API for managing users

paths:
  /users:
    get:
      summary: List all users
      description: Returns a paginated list of 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'
                  meta:
                    $ref: '#/components/schemas/Pagination'

Endpoint Documentation

## Create User

Creates a new user account.

### Request

`POST /api/v1/users`

#### Headers

| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer token |
| Content-Type | Yes | application/json |

#### Body

{ "email": "[email protected]", "name": "John Doe", "role": "user" }

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | Valid email address |
| name | string | Yes | 2-100 characters |
| role | string | No | "user" or "admin" (default: "user") |

### Response

#### Success (201 Created)

{ "success": true, "data": { "id": "usr_abc123", "email": "[email protected]", "name": "John Doe", "createdAt": "2025-01-02T12:00:00Z" } }

#### Error (400 Bad Request)

{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Invalid request body", "details": { "email": "Invalid email format" } } }

Code Examples

Good Example

// ✅ Shows real use case with context
import { createClient } from 'my-api';

const client = createClient({
  apiKey: process.env.API_KEY,
  region: 'us-east-1',
});

// Fetch user with error handling
try {
  const user = await client.users.get('user_123');
  console.log(`Found user: ${user.name}`);
} catch (error) {
  if (error.code === 'NOT_FOUND') {
    console.log('User does not exist');
  } else {
    throw error; // Re-throw unexpected errors
  }
}

Bad Example

// ❌ Too abstract, no context
const client = new Client(options);
const result = client.doThing(data);

Changelog Format

# Changelog

## [1.2.0] - 2025-01-02

### Added
- New `exportToPDF()` method for reports (#123)
- Support for custom themes

### Changed
- Improved performance of data loading by 40%
- Updated minimum Node.js version to 18

### Fixed
- Fixed memory leak in long-running processes (#456)
- Corrected timezone handling for scheduled tasks

### Deprecated
- `legacyExport()` - use `exportToPDF()` instead

### Security
- Updated dependencies to patch CVE-2025-XXXX

Best Practices

1. Write for scanning - Use headers, bullets, tables
2. Show, don't tell - Include working code examples
3. Keep examples minimal - Show the concept, not everything
4. Update with code - Docs rot faster than code
5. Test your examples - Ensure they actually work
6. Link liberally - Connect related concepts
7. Use consistent terminology - Define terms once
8. Include troubleshooting - Common errors and solutions