Developer portals - the documentation is dead, long live the documentation!
I have been working in the integration space for a couple of decades now, supporting many organisations of different sizes and in various areas. Without doubt, I can say that the most unplanned time spent, has been about communication and about how to communicate to the endpoints of the integration platform at hand. That communication includes the not so interactive variant of reading and writing documentation.
And more times than not, that written document was of course not enough to finalize the task at hand, and additional communication had to be initiated through email, a phone call or speaking to a colleague. All in all, a frustrating experience and one of the main reasons onboarding of a new consumer to an integration endpoint does not scale very well. In short, a bad developer experience.
Assuming we all want business agility and happier developers, let’s dive a bit deeper into the pillars and features of a developer portal:
Marketing – knowing that an API exist
The first step to use an API is to know that it exists. Therefore, an easy on the eye page listing the APIs with short descriptions of benefits and use cases is essential. In many cases this could be on the portals start page.
Discovery – understanding what an API can do for me
The API Reference section documents each and every endpoint. You should aim to represent client use of your API for multiple client technologies with code snippets for most common languages. This helps making the documentation suitable for a wider range of experience levels. An interactive API Console gives the developers the opportunity to call and play around with the API without any coding themselves. For a developer this is a much better experience than reading.
Guides – helping me consuming the API from my application
Getting started documentation with step-by-step instructions. Most likely a detailed description of how to access the API (Authentication & Authorization). A lot of code examples is always appreciated.
The developer should be able to request access for their application to the API from within the portal. See the status of the request and of course all active subscriptions.
The portal should offer at least some rudimentary analytics of each subscription showing the usage of the API, average response times, response codes etc.
A support section of the portal with at least maintained FAQs. An active channel for support cases and maybe a community Q&A forum.
I hope this blog has inspired you to consider a Developer Portal or expand your existing to ensure you make developers happy and less frustrated!
Please feel free to contact me for more tips and help in making an awesome developer experience.