by kvantomme / 19 December, 2019
Developer portals & digital transformation: APIs in the complex adaptive enterprise


What is digital transformation?

Depending on the person you ask this question, they will all tell you a different answer. If you ask somebody in the IT industry, their answer will probably be centered around their own services.

For example, for some people, digital transformation is about the digitalization of documents, ERPs, CRMs, APIs, AI,... For others, it is about becoming an Agile organization, about DevOps, Open Source, InnerSourcing, Industry 4.0,...

All these buzzwords are tactical, they are patterns of behavior and technology sets that you can use to achieve digital transformation. For a couple of years now I’ve been researching systems thinking and... Read more

by kvantomme / 28 June, 2018

A developer portal - often shortened to devportal - is the interface between a set of APIs, SDKs, or other interactive digital tools and their various stakeholders. The portal can play several roles to achieve the business goals of an organization.

A lot of API teams publish their "Swagger/Open API Spec" (or RAML, API Blueprint, I/O Docs, WSDL, etc) documentation and call it a developer portal.

However, reference documentation is only one part of the minimum viable developer portal.

Yes, your developer portal needs to contain API or SDK reference documentation (no matter what specification format you use) but a developer portal should also be

a sort of self-service support hub, a trust signal, a communication nexus for stakeholders and a key DevRel tool... Read more
by kathleen / 23 December, 2016

The main purpose of Platform Software Development Kits and Helper/Client Libraries (we’ll use “SDKs” to address these collectively in our writing) is to accelerate and simplify development. A well maintained SDK is a trust signal that indicates the level of support and usage of your API for a language, framework, or development platform. So indirectly SDKs work as social proof, that indicates how many communities are already using your API.

In this post, we’ll look at how the developer portals in our research sample included SDKs. We’ll examine their functions, describe where we found them in the site architecture and deduct best practices.

We’ll discuss what kind of SDKs the Portals in our sample used. We’ll analyze their choices and evaluate them against the... Read more

by steve / 13 December, 2016

Twilio is regarded as one of the API industry’s leaders, so when, after five years, Twilio changes the documentation format on their developer portal, everybody wants to know why. Jarod Reyes and Andrew Baker (both developers of Twilio's developer education team) gave a presentation about the reason for the changes at SIGNAL 2016. Because we found them valuable and wanted to share them with our developer portal mailinglist, we’ll summarize their findings in this blog post.

1. Know what developers don’t need: Narrative vs Code

Twilio considers API documentation to be a product in its own right, not just a supplement of “The Product”. Because developers need documentation to integrate with an API, it plays a key role in the developer experience and overall quality of service. It... Read more

by kathleen / 23 November, 2016

Self-service support is arguably the most important role of a developer portal. Without proper documentation, API teams will spend countless hours on introduction workshops and other training and support efforts.

In this post we’ll analyze the characteristics of a number of support resources and look at how they involve users to develop information about the problem areas in an API’s use. We’ll list pros and cons for the different resources, look at their place in the site architecture, and finally propose best practices.

Support resources are a documentation format

Even the best documented APIs, that complement their API reference with plenty of onboarding tutorials, also have a wide range of support solutions on their developer portals. Twilio, often praised for the... Read more

by kathleen / 17 November, 2016
Reference pages: an API’s inventory and checklist

Once a developer knows how to use your API, they will need detailed instructions on how to build the actual integration. Experienced developers already familiar with an API, including its creators, will have a hard time completing an integration without access to the API reference. That is why developers will often refer to them as “the API documentation”. This is a dangerous practice, as it implies that an API reference would be the only documentation an API needs, we talked about this in our previous posts.

In this post we’ll show how the developer portals in our research sample implemented their reference pages, compare their formats and labels, and try to deduct best practices you could apply on your developer portal.

... Read more
by kathleen / 2 November, 2016
Guides and tutorials: documentation for differently skilled developers

If the primary function of a developer portal’s onboarding page is to help developers self-select their knowledge level and to create an expectation of learning, then the function of the guides and tutorial pages that are linked from an onboarding page is to fulfill this expectation: to design an experience that will be as close as possible to the learning requirements of key audience segments.

In this post, we will explore how the sites we reviewed included guides and tutorials in their information architecture, we’ll look at what they covered, and finish with listing what could help to maximize their effectiveness.

Sharing theoretical and practical knowledge

Guides and tutorials are not always... Read more

by kathleen / 21 October, 2016
The onboarding page, a crucial component for developer portals

Developer experience on first contact is arguably the single most important job of a developer portal. In some cases your API might only have a few minutes to hook a developer, if it isn’t immediately clear where developers can start their integration efforts, they might leave and never come back. This is why onboarding pages are so important. In this article we’ll list the various roles onboarding pages need to fulfill. We’ll also explore how the developer portals we reviewed expose them and how they are labeled.

Different onboarding for different audiences

Depending on the objective and the prior experience of a user, an onboarding page needs to fulfill 3 different roles:

Evaluate: Help developers and... Read more
by kathleen / 13 October, 2016
The importance of overview pages

Even though every page is page one in a post-Google world, a large group of developers will end up exploring your documentation starting from one of your portal’s landing pages. That is why it is really important to provide a front page that gives an overview of the available documentation, an entrance page to the portal where developers can start exploring: the “overview page”. Ideally overview pages clearly refer to (all) documentational components (getting started, API reference, guides, tutorials, FAQ and example pages) and provide links to subpages.

To help developers process the information, links to subpages will be chunked according to a classification system. The chosen classification system will also typically influence the... Read more

by kata / 19 July, 2016
Mistrust

Why is it so hard to register API keys on developer portals? Why is it so time-consuming to get started with an API?

To answer these user questions, we need to understand that there are two opposite intentions about running developer portals. On one hand, every developer portal aims to delight developers with a great product experience and to convince them to register as early as possible. The goal is to reach high conversion rates. On the other hand, companies want only trustworthy people to use their products, they want to avoid misuse. Such security considerations often lead to a painful registration procedure.

If you want to provide a better developer experience (DX) on your portal, you need to understand what makes developers like your portal. As a first... Read more