Software Development Kits (SDKs)

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

FAQs, Forums and Other Support Resources

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

Reference Pages

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

Guides and Tutorials

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

Onboarding Pages

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

Overview Pages

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