Case Study #4 / Technical Documentation
API Documentation: From Sparse to Complete
A developer tools company had API docs with endpoint names but no examples. After adding request/response samples and error handling, support tickets dropped 60%.
Editorial Brief
| Element | Value |
|---|---|
| Content type | API reference documentation |
| Intended reader | Developer integrating the payments API |
| Primary question | How do I call this endpoint and handle the response? |
| Desired action | Successfully implement the API |
| Word count target | 800-1,500 words per endpoint |
Original Draft (Excerpt)
POST /v1/charges
Creates a new charge. Requires authentication.
Parameters: amount, currency, source, description
Returns: Charge object
Word count: 28 words
Initial score estimate: 28
Problem: No examples, no error codes, no authentication details, no rate limits.
Key Revisions
What Changed
- Added curl example: Full request with headers and body
- Added response sample: JSON response with all fields explained
- Added error handling: 10 common error codes with meanings and fixes
- Added rate limits: "100 requests/minute per API key"
- Added authentication: "Bearer token required, here's how to get one"
- Added SDK examples: Python, Node.js, Ruby, PHP code snippets
- Added idempotency: "Use idempotency keys to prevent duplicate charges"
Revised word count: 1,240 words
Estimated revised score: 88
Results
After 4 weeks:
- Support tickets for this endpoint: -60%
- Time to first successful API call: 25 min → 8 min
- Docs page views: +45% (more developers finding it useful)
- "How to" search queries in docs: -35%