Lessons from documenting AI APIs as a solo technical writer
Here's a truth that took me too long to learn: Most API documentation is written for the writer, not the reader.
We document endpoints in alphabetical order because it's easy to organize. We list every parameter because we want to be thorough. We write comprehensive reference docs and wonder why developers still ask basic questions in support channels.
As the only technical writer at an AI startup, I've had to rethink how I approach API documentation. Here's what actually works.
Start With Use Cases, Not Endpoints
The biggest mistake I made early on was organizing documentation by endpoint.
POST /users/createGET /users/listPUT /users/update
Alphabetical. Comprehensive. Completely useless for someone trying to figure out how to get started.
What developers actually want to know:
- How do I analyze a video file?
- How do I monitor sensor data in real-time?
- How do I get my first successful API call working?
Now I start every API section with a use case. Not "here's what this endpoint does" but "here's what you're trying to accomplish, and here's how."
The endpoint reference still exists. But it's not the entry point. The use case is.
Stripe's API documentation is the gold standard here, they lead with use cases like "Accept a payment" before diving into endpoint references.
The Quickstart Is Everything
If your quickstart doesn't work, nothing else matters.
I learned this the hard way when we had a hackathon approaching and our quickstart guide wasn't returning results. The API reference was complete. The conceptual docs were polished. But developers couldn't get past step one.
A good quickstart should:
- Work in under 5 minutes
- Require minimal setup
- Show a real result (not just a 200 OK)
- Be testable by someone who knows nothing about your product
I now test every quickstart on a fresh environment before publishing. If I can't get it working in 5 minutes with just the docs, it's not ready.
Twilio's quickstarts are excellent examples — they get you to a working "Hello World" in minutes.
Code Examples Must Actually Run
This sounds obvious. It's not.
I've lost count of how many times I've found code examples that:
- Use deprecated endpoints
- Have typos in parameter names
- Work in the old API version but not the current one
- Are missing required authentication headers
My process now:
- Write the code example
- Actually run it
- Copy the exact code that worked into the docs
- Add a test to catch when it breaks
That last part is crucial. APIs change. If you don't have automated checks, your examples will rot.
One specific lesson: JSON formatting matters more than you think. I once spent hours debugging why an API call failed, only to discover that multi-line JSON with whitespace caused errors, but compact single-line JSON worked fine. That's now documented with a warning.
Error Documentation Is Not Optional
Most API docs show you the happy path. Request goes in, response comes out, everyone's happy.
Real developers spend most of their time in the unhappy path.
For every endpoint, I now document:
- What errors can occur
- What each error code means
- What likely caused it
- How to fix it
Example:
400 - Missing Required Field
{
"code": "missing_field",
"message": "Missing field: user_id",
"suggestion": "Ensure your request body includes the required user_id field"
}
This takes more time upfront but dramatically reduces support tickets. When developers can self-serve their way out of errors, everyone wins.
Stripe's error handling documentation is worth studying, they document every error code with causes and solutions.
Structure Matters More Than You Think
A few formatting lessons I've learned:
Use tabs for multi-language examples. If you support Python, JavaScript, and cURL, don't make developers scroll past two languages they don't care about.
Lead with the most common case. If 90% of users need the simple version, show that first. Put the advanced options in an expandable section.
Be consistent. If you show request first, then response in one section, do it that way everywhere. Developers build mental models of your docs. Don't break them.
Make copy-paste easy. If developers need to copy an API key, a URL, or a code snippet, make sure it copies cleanly without extra whitespace or formatting artifacts.
If you're using a docs-as-code approach, tools like Mintlify, ReadMe, or Redocly have built-in components for tabs, code groups, and interactive examples.
Test Your Own Documentation
The best feedback on my docs comes from watching someone use them.
When we onboarded new team members, I asked them to mark every point where they got confused. Every time they had to ask a question, that was a documentation failure.
Questions I now ask myself:
- Can someone with no context get from zero to working API call using just these docs?
- When they hit an error, can they figure out what went wrong?
- Are they copying code examples directly, or having to modify them?
If the answer to any of these is "no," the docs aren't done.
The Write the Docs community has been invaluable for getting feedback and learning from other technical writers facing similar challenges.
The 3 AM Test
Here's my final quality check:
Imagine a developer at 3 AM, deadline looming, trying to integrate your API. They're tired. They're frustrated. They don't want to read your carefully crafted conceptual overview.
Can they find what they need in 30 seconds? Can they copy a working example? Can they troubleshoot errors without filing a support ticket?
If yes, your docs are ready. If no, keep iterating.
What I'm Still Learning
API documentation is never done. I'm still figuring out:
- How to document AI outputs that aren't deterministic ("results may vary" is true but not helpful)
- How to balance comprehensive reference docs with practical guides
- How to keep docs updated when the API changes weekly
But the fundamentals stay the same: start with use cases, make the quickstart bulletproof, test everything, and always write for the developer at 3 AM.
Resources That Have Helped Me
- Google's API Design Guide — Principles for designing (and documenting) APIs
- Docs for Developers — The book that shaped how I think about developer docs
- I'd Rather Be Writing — Tom Johnson's blog on API documentation
- Write the Docs Slack — Community of technical writers
What's the best API documentation you've encountered? What made it work?
Top comments (0)