Just thought i’d post my experience as a real world example for anyone thinking of doing the same.
Over at ThatApiCompany, I’m building free public service APIs to let developers of any ability have fun, engaging, educational APIs to practice with. They’ve had 1,000’s of signups across a wide variety of countries & reasons, so they need documentation that helps them get started & answers any questions they have.
I’ve recently migrated two of them (TheCatApi.com & TheDogApi.com) from basic code generated documentation into an API reference, with handwritten example pages, interactive examples & source code - creating a proper developer experience. All hosted on Stoplight.io
Old Version | New Version
Since the move the user feedback has been excellent, as has the numbers in Google Analytics & increase in API usage metrics.
- “The new docs are a vast improvement on the old”
- “Feel comfortable pointing my students at the new documentation and knowing they will understand it”
- “Easy to understand and answered all of my questions”
Other options i tried:
- Open-source doc generators - overhead of setup & maintenance was a continual distraction from actually building the APIs
- Other hosted documentation providers - however they lacked customisation options, e.g. GA tags for insight, OAS exporting, easy custom domain setup etc
- Analytics on which pages / sections are popular is key to understanding ‘what’ users want to do, don’t just rely on API usage stats.
- Interactive examples with source code demonstrate ‘how’
- Personally email as many users as possible for honest criticism / feedback, users can smell automated emails.
- Big takeaway - Create an experience, not just a reference
Summary / TL;DR:
I moved API documentation from single page auto generated docs, to Stoplight powered interactive documentation. This resulted in a 2x uplift in every metric i care about.
- Visitor bounce rate halved, time on docs pages doubled,
- Number of signups successfully boarding doubled.
- Requests for help from users changed from basic questions, to more advanced use-cases.
- Users made more use of advanced features of the API (Voting / Favourites & Uploading)
Investing proper time in developer experience = More API usage & positive outcomes
Thanks for reading