I’ve previously worked on developer / API documentation platform for a startup's Public APIs used by 100s of developers and with 100M+ API calls. Now I’ve also gained experience on the other side — as a developer via AI coding. Here are what I think are must-haves for your developer documentation to have the best developer experience, especially in the world of LLMs with codegen tools like GitHub Copilot, Cursor, and others.
Why is Developer Experience important?
If there is competition for your platform's service, the platform with the best DevEx will win out.
Example: here is an assessment of a very popular dev Pieter Levels (@levelsio) who prefers to use OpenAI or Claude over Google's AI for this reason
Even if there is no competition for your API, or teams have been mandated to integrate your API into their products, developer experience still matters when it comes to execution speed and quality.
Key metrics for Developer Documentation are:
- Time to First Successful API Call (measures how quickly developers can implement and use your API)
- Documentation-Driven Support Ticket Ratio (measures self-service effectiveness)
- Developer Retention Rate (indicates long-term documentation effectiveness)
Good API documentation principles
How easy is it to find what you're looking for?
- How easy is it to get working code?
- How easy is it to know whether something is being deprecated?
- How much time does it take to implement an integration?
- What snippets are available for popular ecosystems like JavaScript, Python, and CURL?
Geared towards LLMs and CodeGen tools
Increasingly, more code will be written by AI than humans. It is better to get your API documentation readable and accurate for LLMs to write code from. And to facilitate building integrations using GitHub, Copilot, Cursor, or other AI coding tools.
The first thing is that the API docs should be parseable by AI agents. So it's not behind a login or paywall, neither is it blocked by robots.txt.
The code examples structure should be consistent and the examples should cover most use cases.
The API docs should be machine-readable.
- Provide OpenAPI/Swagger specifications
- Include JSON Schema definitions
- Offer machine-readable endpoint descriptions
- Structure metadata consistently
- Use standardized data types
Superbase and ShadCN examples are the best examples of easy to implement code snippets for UI (CSS) and Database (Superbase) that has resulted in rapid growth.
Feedback and Support
You should collect feedback from users about what of the API docs is helpful and what isn't , maintaining open communication between users and documentation. Some level of human support is likely required initially if you don't have everything set up and all queries answered yet. But at scale, a feedback channel can be super helpful.
Performance
Performance is crucial — developers usually have to access a lot of information from the API docs and want to work quickly. If accessing different parts of the documentation requires full page loads, then it would slow them down tremendously. API docs should work like a React/Next.js app for seamless navigation between pages and sections. See the below examples from Pinecone.io built on Mintlify for reference.
Learning from Examples
The best way to get started is with Quickstarts, examples, tutorials and cookbooks.
For example, when I was trying to integrate speech-to-text using ElevenLabs, I came across a challenge where I found the code snippet for the function but without any examples of how an integration like this would take place. Only after digging into the API docs, did I find where the same code snippet was used in an example and which was very useful. This highlighted the importance of discoverability and navigation.
AI-Search
I've worked with AI search, including RAG (Retrieval-Augmented Generation) and Vector Databases with sources. It's important to provide not just answers but also sources behind them to address potential hallucinations. Although it’s not a must have feature in the beginning, it could be helpful to your developer users to get answers.
Final Thoughts
Let's face it - great API docs can make or break your developer platform. In a world where AI is writing more of our code, it's not just about having comprehensive documentation anymore - it's about making it both human-friendly and machine-readable.
The best docs help developers ship faster, reduce support headaches, and keep teams coming back. Whether you're competing with alternatives or are the only game in town, investing in quality documentation pays off in developer satisfaction and integration success.
Take a page from what works - Stripe's crystal-clear examples, OpenAI's structured approach, and modern features like AI search. But most importantly, keep listening to your developers and evolving your docs to match their needs. In the end, the goal is simple: help developers build great things with your API, whether they're coding by hand or letting AI do the heavy lifting.