How to Write Documentation Developers Read

The most useful single idea in technical writing is that documentation comes in distinct kinds. The Diátaxis framework identifies four distinct needs, and four corresponding forms of documentation: tutorials, how-to guides, technical reference and explanation. It proposes organizing documentation around those needs.

Diátaxis's primer describes each one.

The distinctions are practical. The primer describes a tutorial as a lesson in which the instructor is responsible for the learner's safety and success, while a how-to guide addresses an already-competent user and is concerned with work rather than study. Reference material is neutral and should mirror the structure of the thing it describes, so a method that belongs to a class appears under that class in the docs.

The most common mistake the framework warns about is overloading tutorials with explanation. The primer's advice is to give the learner the most minimal explanation, such as one sentence on why a step uses HTTPS, and link to an in-depth article for later.

Tom Johnson's overview of Diátaxis on I'd Rather Be Writing summarizes the premise: each content type serves a different user need, and keeping them separated lets each be structured for its own goal. How-to guides, for example, take a recipe shape with prerequisites and ordered steps.

GitHub's documentation guide suggests using the framework as an audit: check whether a tool you use has a reference page, whether there are enough tutorials for contributors to get started, and whether how-to guides explain some of the common tasks people need to accomplish.

The README is the front door. For many projects it is the only page most people ever read. A University of California, Berkeley library guide lists what it should contain at minimum: a brief description of the project, installation instructions, and a short example.

A README that serves developers usually has these sections, in this order.

1. Project name and summary: one or two sentences on what it does and who it is for.
2. Install: the exact command.
3. Quick start: the smallest complete example that produces a visible result.
4. Documentation: links to tutorials, how-to guides, reference and explanation.
5. Contributing: how to run the project locally and submit a change.
6. License.

The quickstart deserves the most care. Fern's guide recommends starting with quickstart guides that walk developers through authentication setup and a single working API call, because that first success builds confidence before advanced features. Fern calls the measure "time to first call", how long a developer takes to make a first successful request. Test it yourself: give the quickstart to someone who has never used the product and time how long it takes them to get a result.

A good quickstart:

• Lists prerequisites up front, such as an account, a key and a runtime version.
• Uses copyable commands, one per block, with no placeholder the reader must guess.
• Ends with a visible result, such as output in a terminal or a response body.
• Links to the next step, usually a tutorial or the most common how-to guide.

Developers scan. GitHub's guide gives practical advice for helping them.

• Use plain language. It suggests checking for acronyms or technical terms some of your audience will not know, and either swapping them for simpler language or defining them in the document.
• Use headings and a table of contents so readers can see where information lives, and use templates with common headings so pages are structured the same way.
• Be consistent with styling. If important terms are bold in one document, make them bold in the others.

A few more habits make pages faster to use.

• Put the answer first. Start a how-to guide with the goal and the steps, not the history of the feature.
• Write headings that say what is below them. "Rotate an API key" is better than "Keys".
• One idea per paragraph, one action per step. Numbered steps should each contain a single thing to do.
• Show expected output after commands so readers know whether a step worked.
• Name things consistently. If the product calls it a workspace, never call it a project in the docs.

Code examples are the most-used part of developer documentation and the part most likely to be wrong. Fern recommends examples that reflect real integration patterns, including error handling, environment variable usage for credentials, and pagination logic, instead of minimal snippets that leave out what production code needs.

Compare two examples for the same call.

// Incomplete: works only in a demo
const res = await fetch("https://api.example.com/v1/orders");
const orders = await res.json();

// Complete: what a developer can actually ship
const res = await fetch("https://api.example.com/v1/orders?limit=50", {
  headers: { Authorization: `Bearer ${process.env.EXAMPLE_API_KEY}` },
});
if (!res.ok) {
  const problem = await res.json();
  throw new Error(`${res.status} ${problem.title}: ${problem.detail}`);
}
const { data: orders, next_cursor } = await res.json();

The second shows authentication, where the key comes from, what an error looks like and how pagination continues. Those are the questions a developer would otherwise ask.

Examples rot as the product changes. Fern's guide recommends automated testing that executes documented requests against staging environments and checks that responses match the documented schemas. Even a simple script that extracts code blocks and runs them in CI will catch most broken examples before readers do.

Reference is the documentation developers return to every day. Stoplight's API documentation guide describes the types of API docs as a continuum from facts to context: a reference describes the endpoints of an API, guides put those pieces together, and examples solve a specific common problem.

For each endpoint, Fern's guide lists what the reference must cover: the method and path, every parameter with its type, whether it is required and its valid values, and responses with status codes, schemas and example payloads for both success and error. Around the endpoints, the reference needs:

• Authentication: supported methods, where to get credentials, how to send them, and how tokens expire and refresh.
• Errors: every error code with what causes it and how to fix it.
• Rate limits: quotas, time windows and the headers that show remaining capacity.
• Pagination and versioning: how to page through lists and how changes are introduced.

Generate the endpoint reference from a machine-readable description where possible. Fern describes OpenAPI as the most widely adopted specification format for REST APIs, and a single specification can drive the reference pages, client libraries and tests. Generated reference stays accurate because it changes when the specification changes. Write tutorials, how-to guides and explanation by hand around it.

The most reliable way to keep documentation correct is to treat it like code. Write the Docs defines docs as code as writing documentation with the same tools as code: issue trackers, version control, plain text markup, code reviews and automated tests. It lists a benefit that matters more than any tool: you can block merging new features that do not include documentation, which pushes developers to document features while they are fresh.

The UK Government Digital Service described the same approach for its technical documentation. Its writers manage content in GitHub so documentation is versioned and matches the way our developers work with code, and anyone can submit a pull request against the docs. The team noted that working this way gives the whole team shared ownership of the content.

A practical docs-as-code setup:

1. Keep docs in the same repository as the code, or in a sibling repository with the same review rules.
2. Write in Markdown or another plain text format.
3. Add a documentation item to the pull request checklist, and review docs changes with the code.
4. Build the docs site in CI, check links and test code examples.
5. Publish automatically when changes merge.
6. Record an owner and a last-reviewed date on each page, and review stale pages on a schedule.

Coding agents now read documentation as often as people do, and they follow it literally. Clear, task-shaped docs help both audiences. Quanta Intelligence skills apply the same idea, packaging how-to knowledge in a structure an agent can load and follow.