Why Documentation Matters

Good documentation:

• Saves time (for you and others)


• Reduces support burden


• Enables self-service


• Captures institutional knowledge


• Scales knowledge infinitely

Bad documentation is worse than none—it misleads.

Types of Documentation

Tutorials

Purpose: Teach through guided experience

Structure:

What you'll build/learn

Prerequisites

Step-by-step instructions

What you achieved

Example:

# Tutorial: Create Your First API Endpoint

By the end of this tutorial, you'll have a working 
REST API endpoint that returns user data.

## Prerequisites
- Node.js 18+
- Basic JavaScript knowledge

## Step 1: Set Up Project
...

How-To Guides

Purpose: Accomplish specific tasks

Structure:

Goal statement

Steps to achieve it

Common variations

Troubleshooting

Example:

# How to Deploy to Production

## Goal
Deploy your application to production environment.

## Steps
1. Run tests: `npm test`
2. Build: `npm run build`
3. Deploy: `npm run deploy`

## Variations
- For staging: `npm run deploy:staging`
- For rollback: `npm run rollback`

Reference

Purpose: Precise technical details

Structure:

• Comprehensive coverage


• Consistent format


• Easy to search


• No narrative

Example:

# API Reference

## GET /users/{id}

**Parameters:**
- `id` (required): User ID

**Response:**
- `200`: User object
- `404`: Not found

**Example:**

bash
curl https://api.example.com/users/123

### Explanation

**Purpose:** Provide background and context

**Structure:**
- Concepts and theory
- Why things work this way
- Trade-offs and decisions
- Broader context

**Example:**

markdown

Understanding Our Authentication System

Why We Chose JWT

We use JWT for authentication because...

Trade-offs

This approach has benefits (X, Y) but also costs (Z)...

## Writing Principles

### Know Your Audience

Write for the reader, not yourself:
- What do they already know?
- What do they need to accomplish?
- What's their context?

### Lead with Value

Get to the point:

❌ "In this document, we will explore various aspects of configuration management, beginning with..."

✅ "This guide shows how to configure the application.
Basic setup takes 5 minutes."

### Use Clear Structure

**Hierarchy:**

markdown

Main Topic

Section

Subsection

**Signposting:**
- "This section covers..."
- "Next, we'll..."
- "See also: [related topic]"

### Show, Don't Just Tell

**Abstract:**

"Use the function to process data."

**Concrete:**

python

Process user data

result = process_data({"name": "Alex", "age": 30})
print(result) # Output: {"processed": True}

### Be Concise

Remove unnecessary words:

❌ "In order to be able to start the application..."
✅ "To start the application..."

❌ "It is important to note that..."
✅ "Note:"

## Structural Patterns

### The Inverted Pyramid

Most important first:
1. TL;DR / Summary
2. Key details
3. Full explanation
4. Background/context

### The Progressive Disclosure

Layer complexity:
1. Basic usage (everyone)
2. Common options (most users)
3. Advanced configuration (power users)
4. Edge cases (specialists)

### The Problem-Solution

For troubleshooting:
1. Symptom (what you see)
2. Cause (why it happens)
3. Solution (how to fix)

## Code Examples

### Make Examples Complete

**Incomplete (bad):**

python
result = process(data) # Where does 'data' come from?

**Complete (good):**

python

Complete example

data = {"name": "Alex", "age": 30}
result = process(data)
print(result) # Output: {"status": "processed"}

### Make Examples Runnable

Reader should be able to copy-paste and run.

### Show Expected Output

python
>>> calculate(2, 3)
5
>>> calculate(10, -5)
5

### Handle Errors

Show what happens when things go wrong:

python
>>> calculate("a", 3)
TypeError: unsupported operand type

## Common Mistakes

### Assuming Knowledge

❌ "Simply use the standard approach"
✅ "Use the process() function: process(data)"

### Outdated Information

- Date or version your docs
- Review regularly
- Note when things changed

### Missing Context

❌ "Don't do X" (Why not?)
✅ "Don't do X because it causes Y. Instead, do Z."

### Walls of Text

Break up with:
- Headers
- Bullet points
- Code blocks
- White space

## Maintenance

### Keep Docs Near Code

Documentation closest to the code is most likely to stay updated:

src/
api/
users.py
users.md # API docs for users

### Version Your Docs

Track changes:

markdown

Changelog

• 2025-02-01: Added authentication section


• 2025-01-15: Initial version

### Test Your Docs

Regularly verify:
- Examples still work
- Links aren't broken
- Instructions are accurate

### Collect Feedback

Ask readers:
- What was confusing?
- What was missing?
- What helped most?

## AI-Optimized Documentation

For AI agents and search engines:

### Clear Structure

Use semantic headings AI can parse:

markdown

What is X?

X is...

How to Use X

Step one

Step two

Common Problems with X

Problem 1

Solution...

### Answer Questions Directly

AI extracts direct answers:

markdown

How long does deployment take?

Deployment typically takes 5-10 minutes.

### Include Examples

AI learns from examples:

markdown

Example: Creating a User

curl -X POST https://api.example.com/users \
  -d '{"name": "Alex"}'

```

Conclusion

Good documentation is:

• Structured for the audience


• Clear and concise


• Rich with examples


• Maintained over time

Write docs you'd want to read. Future you (and everyone else) will be grateful.

---

Next: Code Review for Agents - Reviewing code effectively