Documentation That People Actually Read

Documentation has a reputation problem. Developers write it reluctantly, managers demand it optimistically, and nobody reads it — because by the time someone needs it, it's outdated, incomplete, or buried in a wiki nobody can navigate.

The problem isn't that people don't want documentation. It's that most documentation isn't useful. It's written to satisfy a process requirement, not to answer a question someone actually has. Useful documentation gets read. Everything else collects dust.

The Four Types of Documentation

Not all documentation serves the same purpose. Conflating types is why most docs fail — a tutorial and a reference guide have different audiences, different structures, and different maintenance needs.

Tutorials (Learning-Oriented)

Guides that take someone from zero to accomplishment. "Build your first API with this framework." "Set up the development environment."

Audience: New users who don't know the system yet. Structure: Sequential steps. Do this, then this, then this. Each step produces a visible result. Key quality: Works when followed. Every step must be tested. A tutorial with a broken step in the middle destroys trust.

How-To Guides (Task-Oriented)

Instructions for accomplishing a specific task. "How to add a new database migration." "How to deploy to staging." "How to rotate API keys."

Audience: Users who know the system but need to do something specific. Structure: Prerequisites, steps, expected outcome. Focused on one task — not a tutorial that teaches the whole system. Key quality: Complete and current. If step 3 changed because the tool was updated, the guide must reflect that.

Reference (Information-Oriented)

Comprehensive, factual descriptions. API documentation, configuration options, database schema, environment variables.

Audience: Users who know what they're looking for and need specific details. Structure: Organized for lookup, not for reading front to back. Tables, alphabetical listings, searchable. Key quality: Accurate and complete. Every option documented. Every parameter described with its type, default, and effect.

Explanation (Understanding-Oriented)

Discussion and context. Architecture decisions, design rationale, system overview, "why we do it this way."

Audience: Users who want to understand the thinking behind the system. Structure: Prose. Narrative. Diagrams. Less structured than the other types because understanding is inherently less structured. Key quality: Honest about tradeoffs. "We chose this approach because X, knowing that Y is a tradeoff" is more useful than "we use the best approach."

Why Documentation Goes Stale

Documentation goes stale for one reason: the code changes and the docs don't. This happens because:

Documentation lives far from the code. A wiki article about the deployment process is disconnected from the deployment script. When the script changes, nobody remembers the wiki article.

There's no feedback loop. Nobody knows the documentation is wrong until someone follows it and gets stuck. By then, the damage is done.

Writing docs isn't part of the workflow. It's a separate task that gets deprioritized when there's "real work" to do.

How to Keep Docs Current

Put documentation next to the code. README files in the repository. Architecture Decision Records in an adr/ directory. API documentation generated from code annotations. If the docs live with the code, they're visible when the code changes.

Make documentation part of the PR. If a PR changes behavior that's documented, the documentation update is part of the PR. Not a follow-up task — part of the same change. Reviewers should check this the same way they check tests.

Automate what you can. API documentation generated from OpenAPI specs. Code examples that are tested in CI (so they break when the API changes). Configuration documentation generated from the actual configuration schema.

Accept that some docs will be stale. Perfection isn't achievable. Prioritize keeping the high-traffic docs current: getting started guides, deployment procedures, and API references. Let the rarely-accessed explanations age gracefully.

The README: Your Most Important Document

The README is the front door of your project. For open source, it determines whether someone uses your project. For internal projects, it determines whether a new team member can get started without asking five people for help.

A good README covers:

What this project does. One paragraph. Not the full feature list — the elevator pitch.

How to get it running. Prerequisites, installation, the command to run it. Every step tested on a clean machine. If setup requires more than 5 steps, there's probably a script missing.

How to run tests. The command. Expected output for a passing run.

How to deploy. Or a link to the deployment guide if it's detailed.

Where to find more information. Links to detailed docs, architecture guides, contribution guidelines.

That's it. The README is a starting point, not an encyclopedia. It should get someone from "what is this?" to "I have it running" in under 15 minutes.

Writing for Maintainability

Write Less

The most maintainable documentation is the shortest documentation that answers the question. Every sentence is a sentence that might become incorrect when the code changes.

Don't document how the code works line by line — the code documents that. Document why the code is structured this way, what the non-obvious constraints are, and what someone needs to know that they can't learn from reading the code.

Use Examples Liberally

A function's documentation might be a paragraph of precise description. Or it might be a single example:

# Calculate shipping cost based on weight and destination
calculate_shipping(weight_kg=2.5, destination="US")  # Returns 12.50
calculate_shipping(weight_kg=2.5, destination="EU")  # Returns 18.75

The example communicates the function's behavior more clearly than a description, and it's easier to verify (you can run it).

Date Your Documentation

When a document was last updated tells the reader how much to trust it. A "last updated: 2024-01-15" notice isn't perfect — the content might still be current — but "last updated: 2022-06-01" on a deployment guide for a system that's been restructured twice is a warning sign.

Link, Don't Duplicate

If information exists in one place, link to it from other places. Don't copy it. Copied information diverges when the original is updated and the copy isn't.

Key Takeaway

Documentation gets read when it's useful, current, and findable. Separate tutorials, how-to guides, references, and explanations — they serve different needs. Keep docs next to the code. Make documentation updates part of PRs. Write less, use examples, and date your documents. Invest most in the README and high-traffic guides. Accept that some docs will age — but make sure the critical ones don't.