Writing docs developers actually read

Most documentation is written once, read rarely and trusted less each month. We have been rebuilding our own docs and, along the way, collecting the habits that make a page get read to the end.

Lead with something that runs

Developers arrive with a task, not a curiosity. The first thing on the page should be the smallest example that does the task, ready to copy.

curl https://api.example.com/v1/health \
  -H "Authorization: Bearer $API_KEY"

Explain it afterwards. A paragraph of background before the first snippet is where readers leave.

Keep pages short and single-purpose

A page that answers one question can be found, linked to and kept up to date. A page that answers six becomes a wall that nobody maintains.

A useful length test

If the page needs a table of contents to be navigable, it probably wants to be two pages.

Write examples with real values

foo and bar teach nothing about what a field contains. Use a plausible job ID, an actual date format, a realistic error body. Readers learn the shape of your data from the examples more than from the schema.

Show the failure cases

Every API page should include at least one error response and what to do about it. Support tickets are mostly people hitting the unhappy path that the docs never showed.

Make search forgive typos and synonyms

People search for what they want to do, not for what you named it. They type "login" when your page says "authentication". Add aliases to page frontmatter and check your search logs monthly for queries with zero results; each one is a missing page or a missing synonym.

title: Authentication
aliases:
  - login
  - api key
  - sign in

Keep docs next to the code

Docs that live in the same repository as the code get updated in the same pull request. That is the idea behind DocsFlowy, which we are building: point it at a repository's markdown and publish a searchable site from it. We will say more when there is something to try.

A short checklist

• Does the first screen contain something copyable?
• Is there one clear purpose for this page?
• Are the example values realistic?
• Is the error case shown?
• Can you find it by searching the word a newcomer would use?