In 2020 the DevPortal Awards category for Best API Reference Documentation & Support was created by combining the former category of API Reference Documentation & Post-Integration with the Maintenance & Support category.
Best API Reference Documentation & Support
This category addresses the heart of developer experience. Success in this category also means that a user learns how to find support if needed, and how to maintain an API integration.
- How can devportals improve on API reference documentation? How do they integrate with “try it out” and sandbox functionality?
- How can users find solutions to problems that occurred? Where can they go to look for answers?
- How can users know that their integration will work over a long period of time? How can they plan ahead?
Sendgrid provides easy access for 1. developers who would like to enter the references immediately, and 2. developers who would go through the onboarding information first.
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.
Nexmo (Vonage)’s references are displayed in 3 columns. The screenshot shows their error dictionary. Note the sidebar menu on the left, the example response and a coding language selector on the right.
KPN provides the possibility to open the API references in SwaggerHub and in Postman.
Erste Bank’s reference pages enable an easy switch between the (collapsible) examples / console column via a button on the right.
The Pipedrive devportal users can send test API calls to try out functions by providing values in the “Test endpoint” fields and clicking the button on the Swagger UI. Note the possibility to “star rate” the endpoint.
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?
API users need the best solution to solve their task at hand. You need to convince them —through your devportal— that your APIs and products provide that solution over a long period of time. In other words, building trust and keeping it alive are key: how can you achieve this?
In our previous article, we emphasized the role of self-service support options in both your onboarding processes and your API reference docs. We also pointed out that your users will be more likely to submit personal data if you mirror that with providing valuable information (in advance or afterwards).
In this article, we will address how to solve issues that go beyond self-service support: How can you make sure you guide your users towards the support resources they need? How can you prove that your portal and APIs are updated regularly and that everything works in the best way possible? How can you show that your portal is trustworthy? How can you enroll your users in a programme that will help your organization gain visibility?
We will highlight the criteria that we think define the Best Post-Integration & Maintenance Support, Best Policies & Terms of Use, and Best Community Spotlight & Outreach categories and showcase how last year’s nominated devportals stood out.
First Aid Kit: FAQs & contact forms
FAQs reinforce self-service support. Depending on the amount and character of the APIs, an organization might decide to embed FAQs within the API docs pages or feature them separately. FAQs can have a business profile (answering general or marketing related questions) or a more technical focus.
Ticketmaster lists their FAQs in topic categories and features them on a separate support focused subpage.
Contact forms can serve as a primary source to ask for help and range from very basic forms to more complicated ones. For example, consider:
- How many fields do users need to fill out before they can submit the form?
- Does the form provide an affordance for the user to categorize their request?
- Does the page provide links to related API documentation or other support options that help users immediately?
- Can users attach screenshots that help them demonstrate the issue?
Orange provides a contact form where users can select the type of request from a drop-down list.
Dailymotion asks the user to select a topic focused tile before filling out a contact form.
Ask peers: forums & third-party resources
Forums and third-party resources enable assistance in niche issues and can help make the API documentation on the devportal more precise and complete. However, these support solutions are only useful if there is an active community of contributors: an empty forum or a discussion area with unanswered questions is worse than having no peer-to-peer interaction at all. You might also consider the following questions:
- Do you have people in your organization that can moderate the forum and monitor the answers that users give?
- Do you want to make the investment required to keep users on your site for peer-to-peer discussions, or is it better to reinforce your presence on popular community sites such as GitHub and StackOverflow?
Plan ahead: changelogs, status pages, release notes, updates
Changelogs, release notes and status pages demonstrate how reliable your APIs are. These resources can help to build trust in your devportal, especially when you allow your users to subscribe for updates.
Everything in one place: the support overview page
An overview page dedicated to support options can help users to find the resources that fit their needs best.
Nexmo supports the findability of its resources via a support overview page. Note the buttons to get to the status page (and where users can subscribe to receive updates) and the possibility to submit a request. Extras on this page: links to the API documentation, to support plans, to account management, to third-party community pages and to the FAQs.
The examples in this post are taken from some of the previous DevPortal Awards nominees and winners.
The Best Developer Portals Learn more about the award categories for the Developer Portal Awards and how you can submit a nomination.
All Pronovix publications are the fruit of a team effort, enabled by the research and collective knowledge of the entire Pronovix team. Our ideas and experiences are greatly shaped by our clients and the communities we participate in.
