Documentation Writer

Create documentation that people actually read, understand, and follow.

Documentation Types

1. README Files

Structure:

# Project Name

Brief description (1-2 sentences)

## Features

- Key feature 1
- Key feature 2
- Key feature 3

## Quick Start

Install

npm install package

Use

package do-thing

## Usage

Detailed usage examples

## Configuration

Options and settings

## API

API reference

## Contributing

How to contribute

## License

MIT

What Makes Good README:

• Clear project name
• One-sentence description
• Installation in 3 commands or less
• Working examples
• Common use cases
• Link to full docs

2. API Documentation

Endpoint Documentation:

## Get User

`GET /api/users/{id}`

Retrieves user details by ID.

### Parameters

| Name | Type | In | Required | Description |
|------|------|------|----------|-------------|
| id | string | path | Yes | User ID |
| fields | string | query | No | Fields to return |

### Response

{

"id": "123",

"name": "John Doe",

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

"created_at": "2026-01-15T10:30:00Z"

}

### Errors

| Code | Description |
|------|-------------|
| 404 | User not found |
| 401 | Unauthorized |
| 500 | Server error |

### Example

curl -X GET "https://api.example.com/users/123" \

-H "Authorization: Bearer {token}"

API Doc Structure:

• HTTP method and endpoint
• Brief description
• Parameters (path, query, body)
• Response format
• Error codes
• Example request
• Rate limits (if applicable)

3. User Guides

Structure:

# Getting Started with X

## Prerequisites

- Requirement 1
- Requirement 2

## Step 1: First Action

Detailed explanation with screenshots

## Step 2: Second Action

Continue with clear instructions

## Troubleshooting

Common problems and solutions

## Next Steps

- Advanced feature 1
- Advanced feature 2

Writing Tips:

• Start with simplest path
• One concept per section
• Use numbered steps
• Include screenshots
• Anticipate problems

4. Code Comments

When to Comment:

• Why, not what
• Complex logic
• Non-obvious decisions
• Workarounds
• TODOs with context

Good Comments:

# Using binary search because the list is sorted and we need O(log n) performance
# for real-time autocomplete. Linear search was too slow on lists > 10,000 items.
def find_item(sorted_list, target):
    ...

# Workaround for Safari bug: Safari doesn't handle null values in localStorage
# See: https://bugs.webkit.org/show_bug?id=123456
def safe_store(key, value):
    ...

# TODO(john): This should be refactored into a separate service when we add
# support for multiple payment providers. Currently only handles Stripe.
def process_payment(amount):
    ...

Bad Comments:

# Increment counter
counter += 1  # Obvious

# Loop through items
for item in items:  # Obvious
    process(item)  # Obvious

Documentation Principles

1. Audience First

Identify Reader:

• Beginner? Explain concepts
• Expert? Focus on specifics
• Internal team? Use shorthand
• External users? Full context

Match Tone:

Beginner: "First, install Node.js from nodejs.org"
Expert: "Requires Node 18+"

2. Show, Don't Tell

Bad:

The function processes data efficiently.

Good:

The function processes 1 million records in under 2 seconds on a standard laptop.

Even Better:

# Processes 1M records in <2s on M1 MacBook
# Benchmark: test_process_benchmark.py
def process_batch(data):
    ...

3. Complete Examples

Bad:

# Use the API
client.do_something()

Good:

import MyClient

# Initialize with API key
client = MyClient(api_key="your-api-key")

# Create a new resource
response = client.create_resource(
    name="My Resource",
    type="standard"
)

# Handle response
if response.success:
    print(f"Created: {response.id}")

4. Keep Updated

Version Your Docs:

> Last updated: 2026-03-16
> Version: 2.1.0

Mark Outdated:

⚠️ **Deprecated**: This endpoint will be removed in v3.0. Use `/api/v2/users` instead.

Changelog:

## v2.1.0 (2026-03-16)

### Added
- New `/api/batch` endpoint

### Changed
- `/api/users` now returns created_at timestamp

### Deprecated
- `/api/legacy-endpoint` will be removed in v3.0

Documentation Patterns

Quick Start

Pattern:

## Quick Start (5 minutes)

### 1. Install

npm install my-package

### 2. Configure

const myPackage = require('my-package');

myPackage.configure({ apiKey: 'your-key' });

### 3. Use

const result = myPackage.doSomething();

console.log(result); // "Success!"

That's it! See [Full Documentation](docs/) for more.

FAQ

Pattern:

## Frequently Asked Questions

### How do I do X?

Brief answer with code example.

### Why does Y happen?

Explanation of why with solution if applicable.

### Can I do Z?

Yes/No with explanation of how or why not.

Troubleshooting

Pattern:

## Troubleshooting

### Error: "Connection refused"

**Cause:** The server isn't running.
**Solution:** Start the server with `npm start`.

### Error: "Invalid API key"

**Cause:** Your API key is incorrect or expired.
**Solution:** 
1. Check your API key in settings
2. Regenerate if needed
3. Update your configuration

### Performance is slow

**Cause:** Large datasets without pagination.
**Solution:** Use pagination for datasets > 1000 items:

client.getRecords({ limit: 100, offset: 0 });

Tools and Formats

Markdown Best Practices

Headers:

# H1 - Title
## H2 - Major Section
### H3 - Subsection
#### H4 - Detail

Code Blocks:

Inline `code` for short references.

Block code for examples

def example():

return "example"

Tables:

| Column 1 | Column 2 | Column 3 |
|-----------|----------|----------|
| Value 1   | Value 2  | Value 3  |
| Value 4   | Value 5  | Value 6  |

Lists:

- Unordered item
- Another item

1. Ordered item
2. Another item

- [ ] Task item
- [x] Completed task

Documentation Generators

JSDoc (JavaScript):

/**
 * Calculate the sum of two numbers.
 * @param {number} a - First number
 * @param {number} b - Second number
 * @returns {number} Sum of a and b
 * @example
 * sum(2, 3) // returns 5
 */
function sum(a, b) {
    return a + b;
}

Python Docstrings:

def calculate_average(numbers: list[float]) -> float:
    """
    Calculate the average of a list of numbers.
    
    Args:
        numbers: List of numeric values
        
    Returns:
        The arithmetic mean of the numbers
        
    Raises:
        ValueError: If numbers list is empty
        
    Example:
        >>> calculate_average([1, 2, 3, 4, 5])
        3.0
    """
    if not numbers:
        raise ValueError("Cannot calculate average of empty list")
    return sum(numbers) / len(numbers)

Documentation Checklist

README:

• [ ] Project name and description
• [ ] Installation instructions
• [ ] Basic usage example
• [ ] License
• [ ] Contact/support

API Docs:

• [ ] All endpoints documented
• [ ] Request/response examples
• [ ] Error codes
• [ ] Authentication
• [ ] Rate limits

User Guide:

• [ ] Prerequisites clear
• [ ] Step-by-step instructions
• [ ] Screenshots/diagrams
• [ ] Troubleshooting section
• [ ] Next steps

Code Comments:

• [ ] Why, not what
• [ ] Complex logic explained
• [ ] TODOs have context
• [ ] No obvious comments

Common Mistakes

1. Assumption Dumping

Bad:

Configure your environment variables.

Good:

Set these environment variables:

export API_KEY="your-api-key"

export API_URL="https://api.example.com"

You can find your API key in your dashboard at https://dashboard.example.com/keys.

2. Missing Prerequisites

Bad:

Run `npm start` to begin.

Good:

## Prerequisites

- Node.js 18+ installed
- npm or yarn package manager
- API key from [dashboard](https://dashboard.example.com)

## Start

npm install

npm start

3. Outdated Examples

Bad:

// Example from v1.0
oldApi.call();

Good:

// Current version (v2.0)
newApi.call();

// v1.0 (deprecated) - remove in next major version
// oldApi.call();

4. No Error Handling

Bad:

const result = api.getData();
console.log(result);

Good:

try {
    const result = await api.getData();
    console.log(result);
} catch (error) {
    if (error.code === 'NOT_FOUND') {
        console.log('No data found. Create some first!');
    } else {
        console.error('Error:', error.message);
    }
}

Writing Style

Be Concise

Bad: In order to use this function, you will need to first install the package.
Good: Install the package to use this function.

Be Precise

Bad: The function might return something.
Good: Returns a User object or null if not found.

Be Active

Bad: The data is processed by the system.
Good: The system processes the data.

Use Examples

Bad: The configuration accepts various options.
Good: The configuration accepts:

{

"timeout": 5000,

"retries": 3

}