Devportal Awards 2019 is open for nominations. We are looking forward to your thoughts on public-facing API developer portals!
This is the fourth article in a series that provides background explanations and examples.
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 New DX Innovation, Best Design, and Best Overall Developer Portal
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?
Best Post-Integration & Maintenance Support
This DevPortal Awards category is for developer portals that do an exceptional job in creating trust towards their APIs by clearly, yet innovatively communicating their availability and reliability. Success in this category means a user learns how (1) to find support if needed, and (2) to maintain an API integration.
Troubleshooting options and maintenance support address the fourth and sixth stage of the downstream developer journey:
- Troubleshoot: How can I, as a user, find solutions to problems that occurred? Where can I go to look for answers?
- Maintain: How do I, as a user, know this will work over a long period of time? How can I plan ahead?
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.
How can devportals build trust through a genuine approach in the topic of legal documentation?
We can categorize the search for legal docs into the second and sixth stage of the downstream developer journey. These steps, however, are equally important in the decision maker’s journey.
- Evaluate: How does this organization deal with legal issues? How can I, as a user, check that the API provider plans for the future?
- Maintain: How can I, as a user, stay up-to-date regarding legal details? Where can I check updates and how often do changes occur?
Plan for readability, usability & findability
How can an organization depict legal information in a user-friendly way? You can address a heterogenous group of users more easily when you, for example:
- highlight the most recent changes,
- point out when the docs were last updated,
- provide an overview of all legal docs,
- have short (with common words) and long versions (for legal experts) of the same content,
- make the legal docs findable.
Best Community Spotlight & Outreach
This category addresses devportals with creative solutions or initiatives to show developers that their work is appreciated.
In the downstream developer journey, community and engagement are the most important in the following steps:
- Troubleshoot: How can I, as a user, interact with others to find solutions?
- Celebrate: How can I share what I implemented? How can I show my special solutions? How and where can I meet with others? Can the API provider use my knowledge?
Engage users to find solutions, share knowledge & build connections
How can you help developers troubleshoot, provide and find solutions, share knowledge and build connections? Consider, for example:
- a community page (e.g. to announce webinars and to feature champion users),
- a blog with articles dedicated to interesting solutions that require out-of-the-box thinking (e.g. use cases),
- a third-party community page (e.g. GitHub),
- a discussion forum,
- asking users to write documentation about niche problems (developer docs),
- organizing events and hackathons,
- enabling different contact forms to report bugs and issues directly to your team.
In short, the goal is to enable your users to plan for the future, help them to interact with peers and engage them to share their experience and expertise — all in order to establish trust in your portal and, eventually, turn your users into your portal’s advocates.
DevPortal Awards 2019: How to nominate your developer portal
What is the goal?
The goal of DevPortal Awards 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.