API Documentation: Should You Build or Buy?
What it Takes to Build and Maintain Great Docs
Apr 10, 2019
API documentation is one of the most undervalued assets of a technology company. Most tech companies sell access to APIs that allow customers to retrieve information or use services. Revenue is then generated each time a customer uses the API. In order for customers to use the APIs, they need to understand what is available, how to ask for it, and how it will be returned. All of this information should be provided in the API’s documentation, usually as a website. Therefore, it is very important that your API documentation is performant, accessible, portable, and integrated.
Stoplight Classic’s Documentation
Since there aren’t any static files produced, it wasn’t very easy to port the published documentation into an existing website or developer portal. Most of our customers resorted to embedding their documentation via an HTML iFrame. This works in theory, but it lacks support for linking to subpages.
API documentation is not always standalone. Most of the time, companies want to include their API documentation along with their product documentation. This is usually called a developer portal, or at Stoplight, a Hub. Having the two separate is possible, but it is not ideal for users if they are having to navigate between multiple sites.
AWS CloudFront edge locations
We decided to create our own specification that could combine any number of OpenAPI Specification documents, Markdown and HTML files using JSON references. With it a build tool that could export the specification into a developer portal, optimized for SEO and portability. Thus, the Hub spec and Hub Builder were born:
Stoplight Next’s Documentation Hub
Next vs Classic page load times
Next vs Classic download size and number of requests
Here at Stoplight we are always looking for innovative solutions to maintain a balance between aesthetics and functionality. We don’t want you to have to sacrifice beautiful documentation for speed and performance. We also don’t want the process of creating documentation to be time consuming and arduous. The changes we’ve made thus far have been our first foray into establishing that balance but this is just the beginning. We already have plans to speed up the process even further along with a multitude of new functions and services. I guess you will just have to wait and see!