Documentation Writer

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

Use

Usage
Detailed usage examples
Configuration
Options and settings
API
API reference
Contributing
How to contribute
License
MIT

What Makes Good README:

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

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

API Doc Structure:

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:

4. Code Comments

When to Comment:

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:

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

2. Configure

3. Use

That's it! See Full Documentation 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:

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

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:

API Docs:

User Guide:

Code Comments:

Common Mistakes

1. Assumption Dumping

Bad:

Configure your environment variables.

Good:

Set these environment variables:

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

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:

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

Options and settings

Common problems and solutions