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

bash

Install

npm install package

Use

package do-thing CODEBLOCK1

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

json
{
"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

bash
curl -X GET "https://api.example.com/users/123" \
-H "Authorization: Bearer {token}"
CODEBLOCK4

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:
CODEBLOCK5

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:
CODEBLOCK6

Bad Comments:
CODEBLOCK7

Documentation Principles

1. Audience First

Identify Reader:

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

Match Tone:
CODEBLOCK8

2. Show, Don't Tell

Bad:
CODEBLOCK9

Good:
CODEBLOCK10

Even Better:
CODEBLOCK11

3. Complete Examples

Bad:
CODEBLOCK12

Good:
CODEBLOCK13

4. Keep Updated

Version Your Docs:
CODEBLOCK14

Mark Outdated:
CODEBLOCK15

Changelog:
CODEBLOCK16

Documentation Patterns

Quick Start

Pattern:

## Quick Start (5 minutes)

### 1. Install

bash
npm install my-package

### 2. Configure

javascript
const myPackage = require('my-package');
myPackage.configure({ apiKey: 'your-key' });

### 3. Use

javascript
const result = myPackage.doSomething();
console.log(result); // "Success!"
CODEBLOCK20

FAQ

Pattern:
CODEBLOCK21

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 });
CODEBLOCK23

Tools and Formats

Markdown Best Practices

Headers:
CODEBLOCK24

Code Blocks:

Inline `code` for short references.

python

Block code for examples

def example():
return "example"
CODEBLOCK26

Tables:
CODEBLOCK27

Lists:
CODEBLOCK28

Documentation Generators

JSDoc (JavaScript):
CODEBLOCK29

Python Docstrings:
CODEBLOCK30

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:
CODEBLOCK31

Good:

Set these environment variables:

bash
export API_KEY="your-api-key"
export API_URL="https://api.example.com"
CODEBLOCK33

2. Missing Prerequisites

Bad:
CODEBLOCK34

Good:

## Prerequisites

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

## Start

bash
npm install
npm start
CODEBLOCK36

3. Outdated Examples

Bad:
CODEBLOCK37

Good:
CODEBLOCK38

4. No Error Handling

Bad:
CODEBLOCK39

Good:
CODEBLOCK40

Writing Style

Be Concise

CODEBLOCK41

Be Precise

CODEBLOCK42

Be Active

CODEBLOCK43

Use Examples

CODEBLOCK44json
{
"timeout": 5000,
"retries": 3
}
CODEBLOCK45