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:

  1. Best Accessible Devportal and Best Internationalized & Localized Devportal
  2. Best API Business Model and Best Decision Maker Documentation
  3. Best Onboarding and Best API Reference Documentation
  4. Best Post-integration & Maintenance Support, Best Policies & Terms of Use and Best Community Spotlight and Outreach
  5. 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?

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.

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.

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.

Best Policies & Terms of Use

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?

Legal documentation

Legal docs define the boundaries of the devportal, API and API documentation usage. Devportals can have (e.g.) a partner policy, a cookie policy, terms of use, a privacy policy, terms of service, terms and conditions, an agreement, a license, a code of conduct, a copyright policy, a disclosure and an end user policy to describe these boundaries.

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.

KPN gives an overview of all terms and conditions in a sidebar.

Ticketmaster provides a detailed overview of their legal documentation via the “Support” menu item on top.

Nexmo lists when they last updated their terms of use and provides a link to the older version.

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.

Shopify’s community page enables an easy search, discussions, links to specific topics (note also the legal documentation) and to latest posts. The company also lists their champion authors.

Cisco’s “Community” section in the top menu covers an overview of all community related platforms and support options.

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.

This article was edited by Mark Winberry and Mónika Alföldi-Zörgő. Many thanks to Anna Antal for the background research!

About the author

Kathleen De Roo

Information Architect, Technical Content Writer

Kathleen started as a technical content writer, responsible for doing research and writing on developer portal aspects. As an information architect, she helps clients find out how to align business goals and user needs with the knowledge we gathered about devportals.

She holds master's degrees in history and in archival science & records management.