On this page
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.
Short answer: developers read documentation that leads with a copyable example that runs, keeps each page to one purpose, uses realistic values, shows the failure cases, and can be found by the word a newcomer would type.
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. In our experience, support tickets are mostly people hitting the unhappy path that the docs never showed. Documenting failure modes is also how we approach the APIs we build for clients: an error response is part of the contract.
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 Docs Flowy, 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?
Found this useful? Share it with your team.
Share on LinkedInRelated product
Docs Flowy
Developer Tools
Turn any GitHub repo's markdown into a clean, searchable docs site.



