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?
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?
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?
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.
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?
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.
The examples in this post are taken from some of the previous DevPortal Awards nominees and winners.