Writing Documentation That People Actually Read

Great documentation is the difference between adoption and abandonment. Here’s how to write docs that work.

The Problem

Most documentation fails because it’s written for the wrong audience. Developers write docs for themselves, forgetting what it’s like to not know everything.

The Golden Rule

Write for your future self, six months from now, with amnesia.

Structure

The Pyramid

Start with the answer, then explain:

1. Quick Start: Get running in 5 minutes
2. Core Concepts: How it works
3. Guides: Common use cases
4. Reference: Complete API docs

The Three Questions

Every doc page should answer:

1. What does this do?
2. Why would I use it?
3. How do I use it?

Writing Style

Be Direct

Bad:  "It should be noted that this function may potentially fail..."
Good: "This function throws an error if the file doesn't exist."

Show, Don’t Tell

Bad:  "You can customize the output format using various options."
Good: "To output as JSON, add the --json flag:

       $ mytool --json output.txt"

Use Active Voice

Bad:  "The configuration file is read by the application."
Good: "The application reads the configuration file."

Code Examples

The Three Rules

1. Complete: Users should be able to copy-paste and run
2. Commented: Explain non-obvious parts
3. Tested: Examples that don’t work destroy trust

The Perfect Example

# Load configuration from file
config = load_config("settings.json")

# Process with custom options
result = process(
    config["input"],
    verbose=True,  # Show progress
    timeout=30     # Seconds before timeout
)

print(f"Done: {result.summary}")

Common Mistakes

• Assuming knowledge: Define jargon, link to prerequisites
• Missing error cases: Show what happens when things go wrong
• Outdated examples: Test and update docs regularly
• Wall of text: Use headings, lists, and code blocks

The Payoff

Good documentation:

• Reduces support tickets
• Increases adoption
• Builds trust with users
• Makes your project feel professional

Write docs like you’d want to read them. Your users will thank you.