My Experience porting docs over to Stoplight for theCatAPI.com


(Aden Forshaw) #1

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.

User feedback:

  • “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

Other lessons:

  • 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


(Taylor Barnett) #2

@aden.forshaw this is awesome! :rocket:

Cat dog high five

I love how you added the embedded source code examples in the sections too. I’d love to see more of that with Stoplight.

Bringing the data into the conversation is so key too:

  • 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)

Do you have any future plans for where you want to take the documentation?


(Marc) #3

@aden.forshaw, ditto what @taylor said - this is fantastic, thank you for sharing!

Happy to work with you, and of course please continue to let us know how we can improve :).


(Aden Forshaw) #4

Great question, for me the ones I’ll be working one, but don’t necessarily require any new features are:

  • localisation. the number of signups from SE Asia & South America grows every month, so me doing a better job of supporting them is high on my list.
  • dynamically adding a variable to the page, e.g. a users API_KEY into the example code. I think there’s a way to hack it in, but can’t find much in the way of docs.

Please keep up the great work!