Devportal Awards 2019 is open for nominations. We are looking forward to your thoughts on public-facing API developer portals!
This article is the third in the series. We wrote it to serve with an overview of the nomination categories with background explanations and examples. The article walks through the evaluation criteria.
Posts in this series:
- Best Accessible Devportal and Best Internationalized & Localized Devportal
- Best API Business Model and Best Decision Maker Documentation
- Best Onboarding and Best API Reference Documentation
- Best DX Innovation, Best Design, and Best Overall Devportal
How can you attract and convert new users through your developer portal? How can you make sure your customer developers can easily onboard and integrate with your APIs?
In our previous article, we focused on what can help you, as a user, to decide if a devportal provides you with the solutions you are looking for. In this article, we will look at what comes next: how can you actually start using the devportal and its APIs? How does the authorization process work? How can you run tests? What is needed to begin implementing? How can you accelerate your work?
In this post, we will focus on the categories of Best Onboarding and Best API Reference Documentation. It highlights the criteria that we think define these categories and we showcase how last year’s nominated devportals stood out.
This category is for developer portals that clearly show what their APIs are about, how they work, how developers can start integrating and where they can find resources.
Onboarding information addresses the second and third stage of the downstream developer journey:
- Evaluate: How can I, as a user, test the API? Can I evaluate the API before or after logging in?
- Get started: How easy is it for me, as a user, to register? How can I start using the API that I selected to finish my task? What documentation types are available to help me find out how everything works?
Get started with the devportal & its APIs
The character of your devportal
What authentication and authorization processes do your users need to go through to start using your devportal?
- Do you ask users to register and be logged in before they can access documentation and features?
- Do you provide try-out options before registration?
- Do you provide free try-out options after registration and authorization?
- Do you ask users to go through a staged registration model, where they get access to docs and features depending on their authorization status?
When you communicate the registration process clearly (What will happen when? What do you get in return for what?), you help to set your users’ expectations correctly.
According to the reciprocity principle, users will share personal data more easily if you provide them with information upfront. Evaluation tools (such as samples and demos) and testing tools (such as try-it-out options, a playground, an API explorer, a sandbox environment) can help to give your users a taste of what you will offer them in production. Business requirements and security restrictions influence what you can provide when. Read more on this topic in our article on developer portal user engagement.
API docs & supporting docs
Onboarding documentation can take different forms, e.g.:
- how-to guides, topic guides and tutorials that address onboarding with a clear step-by-step method,
- dedicated blog posts and use cases that explain what a specific API is capable of,
- code samples that provide examples,
- SDKs that provide all the necessary information to use the API (e.g. in a specific coding language),
- conceptual documentation that explains business-specific language,
- other resources, such as visuals that show the API architecture.
Best API Reference Documentation
This category addresses the heart of developer experience:
- How can devportals improve on API reference documentation?
- How do they integrate with “try it out” and sandbox functionality?
In this stage of the downstream developer journey, it is important to figure out whether you know where to find every bit of knowledge that you need to make things work.
Elements that enhance the Developer eXperience
There are lots of features that can make the life of your implementing developers easier. Some examples are:
- highlighted code,
- options to test the API (e.g. via Postman, a built-in console or the try-it-out option in the Swagger UI),
- the possibility to leave comments,
- buttons to copy sample code,
- collapsible columns,
- a programming language selector,
- interactive links,
- an easy way to switch between testing and production environments,
- 1-, 2- or 3-column-style,
- troubleshooting options (e.g. through an error dictionary),
- explanations for classes, methods and parameters,
- information on versioning.
Altogether, it is important to strive for “self-service support inspired” resources on your developer portal: if you make documentation intuitive and easily findable, your users will need less help from outside to solve problems. Good onboarding documentation will make sure you attract new users and convert the people who are visiting your developer portal. API reference documentation, when done well, will provide your (mainly developer) users with the information they need to finish tasks. Does your devportal provides examples that underline these requirements?
DevPortal Awards 2019: How to nominate your developer portal
What is the goal of the DevPortal Awards?
The goal is to recognize public-facing developer portals that show great examples in eleven different categories and to find the developer portal that provides the best overall experience.
Why should I nominate my developer portal?
By nominating a portal you can draw the community’s attention to it and acknowledge the work of the people behind it.
How can I nominate my devportal?
Please fill out the nomination form!
Who chooses the winners?
The winners of the 11 nomination categories will be chosen by the Awards Jury in October. In the Best Overall Developer Portal category two winners will be selected: one by the jury and one by the community via public voting. The portals nominated in any of the 11 categories are running for the Best Overall portal automatically.
How can I stay up-to-date and get notifications?
Sign-up to the DevPortal Awards newsletter and receive info on nomination and voting, nominee and jury news, and details on the gala event.