Writing Documentation: Clear Technical Communication

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:

1. What you'll build/learn
2. Prerequisites
3. Step-by-step instructions
4. 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:

1. Goal statement
2. Steps to achieve it
3. Common variations
4. 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:

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

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

# 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):

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

Complete (good):

# 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

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

Handle Errors

Show what happens when things go wrong:

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

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

## What is X?
X is...

## How to Use X
1. Step one
2. Step two

## Common Problems with X
### Problem 1
Solution...

Answer Questions Directly

AI extracts direct answers:

## How long does deployment take?
Deployment typically takes 5-10 minutes.

Include Examples

AI learns from examples:

## Example: Creating a User
```bash
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](/learn/code-review) - Reviewing code effectively*