documentation-writing

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

```markdown

# Project Name

Brief description (1-2 sentences).

• Feature 1
• Feature 2

```bash

npm install package-name

```

```typescript

import { thing } from 'package-name';

// Minimal working example

```

Basic Usage

Detailed examples with explanations.

Advanced Usage

Complex scenarios and configuration.

Link to detailed docs or inline reference.

How to contribute to the project.

MIT

```

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

```typescript

/**

* 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 {}

}

```

Interfaces

```typescript

/**

* 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;

}

```

OpenAPI/Swagger

```yaml

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

```markdown

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": "user@example.com",

"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)

```json

{

"success": true,

"data": {

"id": "usr_abc123",

"email": "user@example.com",

"name": "John Doe",

"createdAt": "2025-01-02T12:00:00Z"

}

}

```

#### Error (400 Bad Request)

```json

{

"success": false,

"error": {

"code": "VALIDATION_ERROR",

"message": "Invalid request body",

"details": {

"email": "Invalid email format"

}

}

}

```

```

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

```typescript

// ❌ Too abstract, no context

const client = new Client(options);

const result = client.doThing(data);

```

```markdown

# Changelog

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

```

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