Documentation Writer

Write clear, comprehensive documentation. Covers README files, API docs, user guides, and code comments. Create documentation that users actually read and understand. Use when writing docs, creating guides, documenting APIs, or improving README. Triggers on "documentation", "readme", "api docs", "user guide", "how to document".

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

```bash
# 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:**
```markdown
## 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

```json
{
  "id": "123",
  "name": "John Doe",
  "email": "[e-mail]",
  "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:**
```markdown
# 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

```bash
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 for more.

### FAQ

**Pattern:**
```markdown
## 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:

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

## Tools and Formats

### Markdown Best Practices

**Headers:**
```markdown
# H1 - Title
## H2 - Major Section
### H3 - Subsection
#### H4 - Detail

Code Blocks:

Inline `code` for short references.

```python
# Block code for examples
def example():
    return "example"

**Tables:**
```markdown
| 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:

```bash
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

Start

npm install
npm start

### 3. Outdated Examples

**Bad:**
```javascript
// 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:
```json
{
    "timeout": 5000,
    "retries": 3
}