Documentation writing

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

```bash
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
```typescript
/**
 * 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

```json
{
  "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
```typescript
// ✅ 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