Over the past two months I've been reviewing public developer documentation. Thirty sites. Some from companies you've heard of. Some from startups whose documentation is better than companies ten times their size.
I went through each one as a developer would - tried the quickstart, searched for common tasks, copied code examples and ran them, checked how errors were handled. No automation. Just me, a terminal, and a growing spreadsheet of notes.
Here is what separates the docs that developers love from the docs that developers tolerate.
1. Time to first success: under five minutes
The best documentation sites get you to a working result fast. Not "understanding" - a result. A response from the API. A deployed function. Something you can point to and say "it works."
The worst ones start with "About Our Company" and take eight clicks to reach the part where you actually do something. One site I audited required creating an account, configuring a workspace, generating an API key, installing an SDK, creating a project, AND reading a conceptual overview before you could make your first API call. Eleven steps.
The best one? Two steps. Copy a cURL command from the homepage. Paste it into your terminal. See a response.
2. Search returns answers, not pages
Bad search: you type "rate limits" and get a list of ten pages that contain those words somewhere. Good search: you type "rate limits" and get "100 requests per minute for free tier, 1000 for paid" with a link to the full page.
3. Code examples that run
I tested code examples on all thirty sites. Copied them. Pasted them. Ran them.
Eleven out of thirty had at least one broken example on their quickstart page. Common failures: hardcoded API keys that were revoked, import statements for modules that were renamed, response schemas that changed since the example was written.
The sites with working examples all had one thing in common: automated testing in CI.
4. Changelogs that explain WHY, not just WHAT
Bad: "Updated authentication flow. Deprecated legacy endpoints. Performance improvements."
Good: "Authentication: Replaced API key auth with OAuth 2.0. Why: API keys were being shared in public repos. Migration: See the upgrade guide."
5. Error messages that link to docs
The single highest-impact, lowest-effort improvement: when the API returns an error, include a URL to the relevant docs page in the error response.
{
"error": "rate_limit_exceeded",
"message": "Too many requests.",
"docs": "https://docs.example.com/rate-limits"
}
Three of the thirty sites did this. Those three had measurably fewer support tickets about error handling.
What to do on Monday
Pick the easiest one. For most teams, that's number 5 - add docs links to error responses. It takes ten minutes to implement.
Top comments (0)