Writing Developer Documentation That People Actually Read

Nobody reads documentation for fun. Developers read documentation because they are stuck. They have a specific problem, they need a specific answer, and they want it as fast as possible. If your documentation does not solve their problem within 30 seconds of landing on the page, they leave.

This framing changes how you write documentation. You are not writing a textbook — you are writing rescue instructions for someone stuck in the middle of building something.

The Four Types of Documentation

Diataxis framework categorizes documentation into four types. Each serves a different need:

Tutorials: learning-oriented. "Follow these steps to build your first X." For beginners who need guided instruction. Long, step-by-step, and hand-holding.

How-to guides: task-oriented. "How to add authentication to your app." For practitioners who know what they want to do but not how to do it specifically with your tool. Practical, goal-focused, and assumes some knowledge.

Reference: information-oriented. "API endpoint parameters, return types, error codes." For developers who know what they need and want the exact details. Complete, accurate, and scannable.

Explanation: understanding-oriented. "How the caching system works internally." For developers who want to understand why things work the way they do. Conceptual, detailed, and narrative.

Most documentation fails because it mixes types. A tutorial that also tries to be a reference is too dense for beginners and too verbose for experienced developers.

Writing for Scanning, Not Reading

Developers do not read documentation linearly. They scan. They jump to the section that matches their problem. They read the first sentence of a paragraph. If it is not what they need, they skip to the next heading.

Optimize for scanning: use descriptive headings (not "Introduction" or "Overview" — use "Installing the package" or "Configuring authentication"), start paragraphs with the key information (inverted pyramid style), use code blocks for anything that should be copied, and bold the most important phrase in each paragraph.

Anti-pattern: "In this section, we will explore the various configuration options available for the authentication module. The authentication module supports several modes of operation, each suitable for different deployment scenarios." — buried the useful information in filler text.

Better: "Authentication modes: session (default, cookie-based), JWT (stateless, for APIs), or OAuth (third-party login providers). Choose based on your deployment model."

Start with the Most Common Use Case

The first code example on any documentation page should be the most common use case. Not the most basic. Not the most comprehensive. The most common.

For a component library button: the first example should be the button that most people want (a primary button with a label). Not the button API with all props listed. Not a basic button without styling.

For an API client: the first example should be making a request that works. Not configuring the client with every option. Users want to see it work first, then customize.

Code Examples Must Work

Every code example in documentation must: compile without errors, produce the described output, use current API versions (not deprecated methods), and include all necessary imports and setup.

Nothing destroys trust faster than code examples that do not work. The developer copies your example, it fails, and they immediately doubt everything else in the documentation.

Test your code examples. Ideally: extract examples into actual test files that run in CI. When the API changes, failing tests identify documentation that needs updating.

Error States and Troubleshooting

Every documentation page for a feature should include: common error messages and what they mean, troubleshooting steps for frequent issues, and links to relevant discussions or support channels.

Developers most often reach documentation when something goes wrong. If your docs only cover the happy path, you fail them at the moment they need you most.

Format error documentation as: error message (exact text they see), cause (why this error occurs), solution (step-by-step fix), and example (working code after the fix).

The README Pattern

For open-source projects: the README is often the only documentation that gets read. Structure it:

One sentence describing what this does (no marketing language)

Installation command (copy-paste ready)

Basic usage example (working code, most common use case)

Link to full documentation (for everything else)

The README is a landing page. Its job: help the developer decide if this tool is relevant to them and get them started if it is. Everything else lives in docs.

API Reference Documentation

For REST APIs: every endpoint needs method and path, description (one sentence: what does this do?), request parameters (name, type, required?, description), request body (schema with example), response body (schema with example for success and error), and authentication requirements.

For code libraries: every public function/method needs the signature with types, a one-line description, parameter descriptions, return value description, one minimal example, and notes on edge cases or exceptions.

Generating API reference from code (TypeDoc, JSDoc, Swagger): automate the structure but hand-write descriptions and examples. Auto-generated descriptions from parameter names are useless: "userId: the user ID" adds no information.

Keeping Documentation Updated

Documentation rots. APIs change but docs do not. Features are removed but their docs remain. New features ship without documentation.

Strategies: documentation as part of the definition of done (feature is not shipped until docs are updated), CI checks for broken links and outdated code examples, documentation reviews alongside code reviews, and automated API reference generation from code (stays current automatically).

We use a documentation checklist in our PR template: "Does this change require documentation updates? If yes, include them in this PR."

Measuring Documentation Effectiveness

Track: search terms that lead to documentation pages (what are people looking for?), time on page (long time might mean confused, or might mean reading thoroughly — context matters), support questions that documentation should have answered (gaps), and documentation feedback (thumbs up/down on pages).

The best signal: when support volume decreases for a feature after improving its documentation. This directly proves the docs are working.

The One Rule

Write documentation for the person who has a specific problem right now and needs to solve it in the next 2 minutes. Not for the person browsing casually. Not for the person reading comprehensively. For the stuck developer who landed on your page from a Google search.

If every page solves one specific problem clearly: your documentation is excellent.