Skip to main content

Analyzing the API docs and DX Patterns in the Best Telecommunication Developer Portals

Information Architect, Content Writer
Aug 06, 2018

The telecommunication sector was one of the earliest adopters of APIs and today it is one of its most important and largest markets. During our research we examined both telecommunication carriers and companies like Nexmo and Twilio, which are often referred to as API vendors. What we were suspecting from the number of publicly available developer portals among the two groups has been confirmed by other resources too: as a developer or a system integrator will most likely choose an API vendor when in need of an API, these vendors are more likely to invest highly into their public facing developer portals. More traditional telecommunication carrier companies on the other hand benefit greatly from internal and partner facing developer portals, as they can facilitate the development of new services and remove friction for their internal and partner developers. However, more and more carriers have started to commit to an external API program, and we really wanted to also include them in our sample.

That is why in this post we would like to present some great examples offered by a selection of telecommunication carriers from all around the world, such as Orange and Telenor from Europe, AT&T from the USA and Telstra from Australia and also by API vendors such as Proximus EnCo, Nexmo and Twilio.

We will evaluate along two main areas:
(1) the available information sources to onboard a developer (such as tutorials, conceptual and legal documentation, support, use cases, etc.),
(2) API docs quality criteria (interactivity, readability, usability, information on pricing).

 

Developer Portals with Brilliant API Docs Solutions

You can read more about the background to these two concepts and why we chose them in our introductory post.

Read more

 

We modelled the steps taken by a developer persona looking for an API implementation from start to finish, and we follow this downstream developer journey to find the industry’s current most innovative and remarkable solutions in architecting and presenting information on a developer portal.

Modeling the downstream developer journey steps on a developer portal

 

Discover and research

How can this portal help me solve my specific task?

Most companies have a site for API marketing and a separate site for the API’s developer documentation. From what we’ve found, Nexmo’s marketing site contains information that we can often find on developer portals, such as an overview of the APIs, use cases, success stories and a blog. The general site, nexmo.com, gives an overview of the whole platform and also of the APIs but the documentation for each API and a try out section is also available from this site’s menu pointing to the developer portal. This shows that it actually targets both developers and decision makers. The devportal, developer.nexmo.com is an API catalog with developer documentation in the strict sense: overview, guide, tutorial and reference.

API catalog on Nexmo’s developer portal.

 

Developer portal landing pages often focus on the products themselves by providing a catalog. AT&T offers various products that they present on the landing page of their developer portal. The APIs are clearly indicated.

Product catalog of AT&T, with indication of the APIs.

 

Telenor, Orange and Twilio have a lot of external APIs, these are presented in groups according to their scope. This method can help users find what they need more easily.

 
 
Telenor, Orange, Twilio APIs grouped according to their scope.

Proximus EnCo offers different entry points for different audiences: the EnCo Market links to their API (and other products) catalog, but code-oriented developers can register right away. For first-time visitors there is also a short video explaining what Proximus EnCo is about.

Different entry points on Proximus EnCo’s landing page

 

Nexmo has detailed, decision maker focused overview pages for each API. There are illustrative use cases to show the possibilities of the API and also partner showcases of real life integration successes. The relevant blog posts are also highlighted on these pages. We must mention that Nexmo seems to be doing an exceptional job at providing the right information and entry point for all of its possible audiences - the menu on the API overview pages offers four options: For your business, For your build, Features and Pricing.

Once users have found the API they are interested in they might want to get a clear iteration of what it is capable of, what it can be used for. There are different methods to provide this. Orange inserts several visuals into the overview of its APIs.

Orange visual in the API overview

 

For its Form filling API Orange also provides a use case in form of a video.

Telstra has an interesting approach for providing an overview for its Event Detection API - the most important features are revealed in the form of a Q&A.

Telstra main features of the Event Detection API

 

Evaluate

Can I trust this organization’s commitment to its APIs?

In our understanding, the evaluation phase is on one hand about making sure that the organization and its APIs are trustworthy, and on the other hand about getting an understanding of the workings of the API(s), often through setting up a test account.

Most portals make it possible to test the APIs after a simple registration process. The required information for registering is usually name, email address and professional background. Nexmo’s registration form has two features that need to be highlighted. One is that not only the links to Terms of Use and Privacy Policy are available right under the registration form, but it also offers the possibility to unsubscribe from Nexmo’s newsletter. They also have an automated field that identifies the user’s phone number country code by their IP address.

Nexmo registration form

 

As we have mentioned in our previous posts, proper information on versioning and release notes are prominent in inducing trust in your APIs. They often get prime real estate on a developer portal, like on AT&T’s or Orange’s site. Orange also has a Release log for each API (where relevant).

Example for an Orange release log

 

Get started

Where do I begin? Well-designed tutorials, quickstarts and how-tos are probably the best antidote against API friction in the getting started phase.

Twilio uses an interesting approach, probably with the aim to better guide its users: the quickstarts are step by step guides. They are broken up into smaller parts, and in the end of every section users can confirm that they have understood the previous part and ready to go on to the next one.

Twilio quickstart 1st step with confirmation in the end
Twilio quickstart 2nd step with confirmation in the end
Twilio quickstart 3rd step with confirmation in the end

 

Twilio’s user friendly solution doesn’t end here. The quickstart contains several screenshots, which can be enlarged by clicking on them, and it also offers a video version of the whole process.

Twilio screenshots in the quickstart that can be enlarged

 

Making sure that users understand the terminology relevant to the industry of telecommunication and the world of APIs can help a lot in the getting started phase.

Nexmo offers a list of concepts of API terminology on its general documentation page, and it also highlights the relevant concepts on the specific API’s page.

Nexmo terminology

 

Orange Developer also begins its getting started documentation with a terminology list.

Orange terminology

 

Filling the getting started documentation with visuals on the workings of the APIs or the authentication processes can help users easily understand the products without having to read lengthy texts.

Great solution for this are provided by Telenor, AT&T and Nexmo.

Visuals in Telenor’s getting started documentation
Visuals in AT&T’s getting started documentation
Visuals in Nexmo’s getting started documentation

 

Structuring the getting started documentation around SDKs might also be a good idea, especially for code-oriented developers.

Twilio offers SDKs with various options in their Quickstart section. Not only can you check the output for the code with a simple click, but its GitHub repository is also available the same way. There is also a copy button or a link can be assigned to various parts of the code.

User friendly tools from Twilio

 

Orange dedicates a whole section to Tools that are aimed at helping developers. Apart from SDKs it also offers monitoring and testing apps, as well as Brand guidelines.

Tools from Orange

 

Nexmo also offers SDKs for different languages. The style of this section suggests that Nexmo would like to gain the trust of developers even with its appearance: the tiles of the SDKs follow the icons and style used by GitHub. Most developers are familiar with this style so it is a user friendly solution for them - it makes scanning for relevant information much easier.

SDKs from Nexmo

 

Implement and troubleshoot

Do I know everything to make this work?

Although reference documentation in itself is not enough for a portal, it is still one of the most important components. Similarly to banking and FinTech portals, the three-column reference docs structure is popular among telecommunication portals too.

Twilio enhanced their three-column references with great tools, such as Output, Copy, a Link to this Code , and access to their GitHub repository buttons. Nexmo also has three-column layout for reference docs with a language selector.

Twilio three-column reference

 

To make it easy for developers to work with the APIs various troubleshooting options are a must. Generally we can talk about three forms of troubleshooting here: self-service support, such as FAQs and knowledge bases, peer-to-peer help in the form of community sections and forums and professional assistance from the API provider, usually attainable via a contact form. The developer portals we have checked in the telecommunication industry provide great examples for all three.

Several portals, for example Orange, Nexmo, Twilio and Telstra have Support or Help section from which the above mentioned resources are available.

Orange support options

 

For FAQs it seems to be a best practice to clearly tag them according to the specific API or the general problem area, like Orange or Nexmo do. AT&T and Orange uses a different approach: the focus is not on a separate FAQ section, but the documentation for each API contains the relevant FAQ. A useful extra with AT&T is that the dates when the answers were given or last updated is also indicated.

AT&T’s FAQ with the data of the latest update

 

The research we consulted showed that developers often turn to third-party resources for peer-to-peer help. In a previous blog post we have argued that these platforms can have numerous advantages, for example developers most probably have an account so they are already aware of the culture required. One of the most popular choices is usually StackOverflow, so it’s not surprising that Orange and Nexmo both offer access to it on their support pages.

Nexmo third-party resources for support

 

Every portal that we checked offers a contact form, but there are exemplary solutions. Does it seem enough to provide an email address users can write their problems to? The whole support process can be made much more effective if the relevant person/department gets your question, with the details they need to actually help you. On Orange’s support section users are asked to choose from five categories with several subcategories in each.

Orange contact form

 

Twilio also has a very detailed contact form. It asks for a detailed description of the problem, and you can further elaborate with an attached file. Users should also indicate the urgency of the problem in the contact form, which again can make support more effective.

Users can indicate the urgency of the problem they’re reporting on Twilio's contact form

 

AT&T has a similar solution. It offers several routes for self-help: check the FAQ, turn to the forum or check Twitter. Direct support can be reached by submitting a ticket, for which users have to choose a topic and they can also indicate the priority of the problem.

AT&T support options

 

Telstra also has various options on its support page: they refer one to a Forum, a Twitter account and an email address. What it highlights is a separate sales enquiry contact form and a phone line dedicated to billing enquiries, and for users who purchase an API plan it also offers a 24/7 support desk. Twilio also offers a separate Talk to sales option on its support page.

Celebrate

Will they care about my work? A developer portal can show appreciation towards its users by asking for their feedback (and taking it seriously). Nexmo asks if users found their documentation useful with a simple choice up or down and asks for optional suggestions on improvement. There is also a link to GitHub for users who prefer this way of communication.

Nexmo feedback

 

Behind sign-in Nexmo uses an integrated external UX tool to collect feedback: users are asked to give a 1-5 rating and share their experience using a handy tool to select and show which part of the site they are giving their opinion on.

Nexmo detailed feedback (behind authentication)

 

Kat King, developer educator at Twilio narrated in a presentation last May how they leveraged direct user feedback (from Twitter) towards a better UX. They went on to ask for both quantitative and qualitative feedback on their docs and have been working on improving them ever since based on the collected data. First users can rate the docs on a scale from one to five and if the rating is 4 or below they are asked to suggest improvements.

Twilio quantitative feedback
Twilio qualitative feedback

 

A well-maintained community section can be beneficial for both users and API providers. On one hand it again shows users that their efforts and opinions are appreciated, on the other API providers can easily get an insight into the interests and preferences of their users. The Events and Blog section of AT&T show that they pay great attention to community building. The first contains numerous events for developers while the second offers reading in various topics which can be filtered by category.

Twilio and Proximus EnCo also have a blog, while Nexmo nudges all the “resources for and by the community” in one place: its Community section contains videos from Youtube, upcoming events and a Slack channel.

Nexmo’s devportal goes for recruitment too: it calls for one’s job application right on top of the page. The “We’re hiring” sign links to the job advertisements, where apart from listing the present team members Nexmo makes a small, yet important gesture towards the community: it highlights the list of contributors on GitHub.

Nexmo recruitment
Nexmo list of GutHubcontributors

 

Maintain

How hard will it be to keep this running?

One of the easiest ways to generate trust towards an API is effective communication of the relevant changes in its status: this allows long-term planning of integration. Orange’s APIs are available in different countries, and they provide the terms specific for the API in the relevant country. Twilio’s cookie policy is very decent: they use a third-party service provider for their cookies, and users can choose from three presets what details they accept to be tracked.

Twilio cookie settings

 

Nexmo and Twilio set a great example by providing a separate API service status page. Both pages follow the same layout structure. It helps the user identify the relevant information faster. We can say that the two companies are offering a pattern that can be used as a best practice. The most recent updates are highlighted on top. There is a possibility to subscribe to updates, and past incidents can also be checked as you scroll. Another extra feature that provides information on the working of the APIs is the system metrics.

Nexmo service status
Users can subscribe to service status updates on Twilio’s portal

 

After signing in to the Nexmo platform we discovered one more little gesture that can help in building trust: apart from the usual confirmation mail I got an automated email from one of Nexmo’s support person, offering his assistance via email or phone (for which I also got a number).

Quality checklist

A sandbox environment does not seem to be a common practice among telco developer portals, unlike in the case of banks and the FinTech sector.

The portals we checked do pay attention to interactivity, and to give an opportunity for users to try out the APIs. Nexmo for example provided credentials and a €2 free credit after sign up.

Nexmo offers €2 free credit for try out

 

Twilio strives to enhance readability by breaking up the quickstart guides to smaller chunks. Nexmo uses a technique that we have also noted in FinTech portals part of this series: it offers a Table of Contents at the beginning of each part of the documentation.

Table of Content at the beginning of each section on Nexmo’s portal

 

The dynamically changing URL, which provides a direct link to each section of the documentation that we can see with Proximus EnCo, Nexmo, Twilio is a feature that can greatly enhance usability. Besides the URLs Twilio uses breadcrumbs to make it easy for users to navigate back and forth in the documentation.

Breadcrumbs on Twilio's portal

 

Information on pricing is super important of course and there are great examples on how it can be provided clearly among the portals we have checked. Both Nexmo and Twilio offer a table describing the services provided by the different support plans, while Proximus EnCo has an additional downloadable spreadsheet with information on pricing in all the countries where its SMS API is available.

Nexmo's support plans

 

The developer journey stages and great API documentation practices

Stage Think about
Discover Landing page
Visuals on the working of the APIs
Case studies
Evaluate Information on versioning
Fast and easy registration process
Get started Quickstart
Visuals
Training videos
Terminology
Implement and Troubleshoot Reference docs
FAQ section
Community section
Tools
Celebrate News & Events
Blog
Feedback opportunity
Maintain Changelog
Release notes
Cookie policy

 

Beyond great documentation

We firmly believe that no matter how great an API is, without a good developer portal it can never achieve its full potential. Twilio, one of the biggest API vendors, has been cited as an example to follow among developer portals for a long time, and there are other portals too that are worth checking. We hope we could come up with a comprehensive sample of developer portals and best practices offered by them. However, we might have missed some portals, so feel free to recommend them in a comment below or even better, nominate them for the DevPortal Awards.

The portals we analyzed

For this part of our series we brought examples from the following developer portals:

 

Thank you so much Kathleen De Roo, Laura Vass and Kristof van Tomme for the editing!


APIDays Amsterdam

Monika presents these research results at APIDays Amsterdam on 17 October 2018. See you there!

APIDays Amsterdam


Posts in this series:


Mónika started at Pronovix as a content writer. While doing research for the Pronovix blog posts she got fascinated by Information Architecture and UX. Apart from continuing her research into devportal best practices she works with clients in the information architecture phase.

Newsletter

Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.

 

Subscribe