Write the Docs is a global community of people who care about documentation. They boast a Slack network of thousands of members and are physically present on 3 continents where they conduct regular meet-ups.
Our team ran into some members of the San Francisco Chapter earlier in the summer, and an arrangement was made for Nauman, our Product Manager to speak at their latest meet-up. With this talk, we aimed to introduce the latest practices in API Documentation and explain what Developer Experience is for APIs.
“….APIs are not only for savvy developers or tech companies”
The talk started off with how APIs are slowly taking over the world, and how it has become important for every business to have an API. The cyberspace is changing rapidly, and just like it was important for businesses to have a website a few years back, it’s important for them to have an API today to exist and stay relevant.
APIs are not as easy to interact with and require prior documentation and know-how for third-party interactors to deal with, in the case of APIs, the third-party interactors being developers, which brings us to the concept of Developer Experience.
Developer Experience (DX) is the equivalent of User Experience (UX) when it comes to a developer.
It is a concept often referenced in the API world and rightly so. APIs are complex structures and unless you properly explain what your API does, nobody is ever going to use it. In fact, the value of your API and the usage is something that directly depends on your Developer Experience.
Developers are the lifeblood of an API economy and until it is made easy for them to access and play around with your API, it may never really see success.
A great Developer Experience is when even novice developers come to your API and require minimum onboarding time, no handholding, and achieve maximum satisfaction. Here, the 3:30:3 Rule is applied which a developer coming in of any experience should take:
This should be the end goal of your entire Developer Experience campaign. These are the metrics you should measure your efforts against at end of the day. Companies like Stripe and Twilio have come close to this and have found massive success with their APIs.
Great Developer Experience can be achieved with the help of the following components:
It is essential to take the correct steps and measures throughout your API Lifecycle to ensure you end up providing a great experience. You can read in detail about the best practices you can follow throughout your API lifecycle.
Your primary focus should be on getting your specification right and how that will drive your entire API Program. No matter what specification you are comfortable with, OpenAPI, RAML, or API Blueprint, you can convert back and forth as many times as you like with the API Transformer and can even integrate the Transformer API in your CI/CD cycle to convert specs on the go.
Coming to the consumption part, Twilio, Stripe, Algolia, and other API companies achieved their success by making their APIs super easy to consume. However, it is important to note that, for all of these companies, APIs are the bread and butter and they can afford to spend their entire resources towards a better Developer Experience. But traditional companies like banks, airlines, and telcos that are recently jumping into the API space or are opening up their API to wider audiences, may necessarily not have the expertise or the knowledge to pull of something similar.
But that does not have to be the case anymore and that’s where APIMatic comes in. With us, you can produce everything that makes it easy for developers to consume APIs. You can provide a Developer Experience only parallel to the best in the industry. And all of that with the least of effort (in minutes) and least of resources. All you need to do is manage and maintain a specification, and let us do the rest.
Don't miss reading APIMatic's philosophy behind automating the developer experience: Introducing Portals That Speak Your Devs Language
We’d like to throw a special thanks to Monique, for doing such a superb job organizing the event and Richard for recording all the videos.