Skip to main content
Information Architect
Dec 21, 2017

What information is absolutely essential on a developer portal? What kind of API documentation do you need? Is there a best practice that can be followed when launching a developer portal? In this post, we share the insights we’ve learned working on developer portals the last couple of years.

A quick look at some (API) developer portals will demonstrate that they can be very different in architectural structure and layout. That is remarkable, because most of the portals not only need to provide similar end results, they also address comparable audiences.

We formulated 11 questions that can help you define the content of your portal to address the documentation needs of your stakeholders. To illustrate how it can be done in practice we built 3 mock sitemaps for developer portals and examine how they address the different stages of the developer’s journey.

What is a developer portal?

A lot of API teams publish their “Swagger” documentation and call it a developer portal. That is wrong on two accounts: the documentation format formerly known as Swagger is now called the Open API spec, and more crucially, reference documentation is only one part of the minimum viable developer portal.

Yes, your developer portal needs to contain API 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 API stakeholders and a key DevRel tool that helps an organization to provide the best possible developer experience for its APIs.

alt
A developer portal is the interface between a set of APIs and their various stakeholders. The portal can play several roles to achieve the business goals of an organization.

 

alt
What is the difference between a developer portal and API documentation? (Write the Docs slack channel discussion recap)

 

11 questions your developer portal needs to answer

We compiled a first list of questions that provides users with the information they might need while working with your API product:

  1. What is this API?
  2. How do I get started with this API?
  3. What do I need to understand about this API?
  4. How do I get X done with this API?
  5. Do I know all the details of this API?
  6. How do I use your API in Y?
  7. Is somebody still working on this API?
  8. Where do I go when I have a problem with this API?
  9. How do I get access to this API?
  10. Can I afford this API?
  11. Can I trust this API?

Most of these questions can have a dedicated section on a developer portal and detailed documentation types can be used to address them. In an MVP however, it is possible to answer these questions without having dedicated sections.

Throughout this post, we will focus on the (API consuming or also “downstream”) developer’s journey and apply the following colors to depict its 6 stages:

alt
The 6 stages of the downstream developer journey are discover/research, evaluate, get started, develop and troubleshoot, celebrate, maintain.

1. What is this API?

Landing pages show the site architecture, help to find and navigate documentation, show what the API offers. Regardless their layout and design, landing pages (also called overview pages) best answer 5 questions immediately:

  • What is the API about? (Purpose and main features of the API)
  • How does the API work? (Technical architecture and programming workflow)
  • How can I start integrating? (Implementing the API according to a developer’s personal learning strategy)
  • Where can I find resources? (Structure of documentation)
  • Can I trust this API? (Trust signals in the broad sense, like pricing information, release notes, usage policies, API status) 
alt
An example of landing page elements that address users with different learning strategies (concept-oriented vs code-oriented approach). Note that the architecture and programming workflow explanations can also provide information about access restrictions. The help and support section ideally answers several questions at once. [This visual was inspired by the findings of Peter Gruenbaum (2010) and Kata Nagygyörgy (2015) and extended with the insights that M. Meng et al. (2017) and Diána Lakatos (2017) provided on the subject.]

 

alt
7 trust signals for your developer portal: business model, partner policy, API quality, API uptime status, versioning policy, documentation and developer portal production quality.

 

 

2. How do I get started with this API?

Tutorials show how to do something step-by-step. Their primary role is to onboard users according to the “Reading to learn to do” principle. Include code examples to enable quick onboarding. 

alt
Tutorials are especially great in the Getting Started stage of the journey. Asking your developers to write tutorials can help them to celebrate their implementation work and create valuable resources for specific product use cases. To some extent tutorials can also help in the evaluation and discover/troubleshoot journey stages.

Other ways that help developers to get started are:

 

  • Prototype building options (mock APIs, sandbox environments, test APIs),
  • A glossary that explains concepts, and gives informative explanations for objects, methods, and parameters.
  • Software Development Kits (SDKs) that focus on implementations in a specific programming language.

3. What do I need to understand about this API?

Conceptual docs explain portal specific concepts. Knowledge of portal and business specific words - like “dunning”- are not only important for developers that don’t know your industry, also more experienced developers less familiar with your product might benefit from a refresher about certain words in your domain language. There is a good chance that your organisation has developed a unique semantic meaning for at least a few words.

4. How do I get X done with this API?

Guides explain how to get something done. They explain how to solve problems via use cases, recipes or cookbooks. Guides take different formats:

  • Topic guides can provide explanations and background information and help contextualize the topic,
  • How-to guides and quickstart guides usually focus on the onboarding process.

alt
Guides that provide code snippets or code examples can play an important role in the onboarding process. In the format of use cases they help evaluate (“Can I get my specific task done with this product?”) and celebrate interesting implementations. Guides are also important in the research and develop phase (how can this be done theoretically and practically?).

5. Do I know all the details of this API?

Reference docs are crucial in the development and troubleshooting stage of the developer journey: they give detailed instructions on how to build the actual integration. API reference documentation is so important that API teams often mistakenly equate “API docs” with the reference documentation of an API. Welcomed as useful extras in reference documentation are:

  • An error dictionary that describes error handling,
  • Information on alternative classes, methods, parameters (where appropriate),
  • Descriptions,
  • Comments,
  • Conceptual information.

6. How do I use your API in Y?

SDKs (Software Development Kits that are community driven, handcrafted or generated) simplify development and help the developers that consume your API to implement best practices they might not be aware off. They have several functions throughout the developer’s journey:

  • Evaluate (internally): by its nature an SDK needs to implement all or a large part of an API’s functionality. That is why it is a great opportunity to review and improve on an API’s design and implementation,
  • Getting started: SDKs make it easy to start implementing in a specific programming language or framework, and help developers to overcome common problematic areas (like authentication),
  • Develop and troubleshoot: Implement API calls in a popular programming language, so that developers can work in their favorite language or platform,
  • Celebrate: Put developers in the spotlight that have created or contributed to an open source SDK,
  • Maintain: SDKs can help keep applications in sync with API changes when used as a dependency in a project, and SDK metrics provide insight into API usage across the different developer communities.

7. Is somebody still working on this API?

API release notes (also called changelog) provide notifications about changes in the documentation. A regularly updated changelog is an important trust signal for your portal. Blogs can communicate solutions on a regular basis and can help prototype new content. If you have people to maintain and update your blog regularly, they can be a perfect content type to incubate new content, publish interesting usage scenarios, communicate changes and company strategies. 

alt
There are several tools available to generate and structure your reference documentation — at Pronovix we normally use Drupal modules to publish reference documentation. But even if you are not building your portal in Drupal you can learn more about free and open source API documentation tools in an article we published previously.

 

alt

Explore the role of blogs in the developer journey.

 

alt
Your blog can play a role in the 6 stages of the developer journey, but our research showed that they are mostly used to engage users in the discover/research, evaluate and celebrate journey stages.

 

8. Where do I go when I have a problem with this API?

Support resources can offer solutions to niche problems and test documentation accuracy. We make a distinction between staffed support and peer-to-peer support:

  • Staffed support can contain an audience focused FAQ page, a knowledge base, support pages where you can directly contact the company’s support team,
  • Peer-to-peer support is about facilitating communication between users via a community section, a developer forum or a third-party community page (e.g., on GitHub).

Support resources mostly address questions related to the getting started and develop/troubleshoot journey stages.

9. How do I get access to this API?

A fast and easy-to-use API key generator improves developer experience (DX): include a link in the code examples, sandbox environment, reference documentation and other pages where your users start implementing the API.

10. Can I afford this API?

Depending on the role and objectives of your visitors, unclear information about your pricing and business model might become a blocker.

11. Can I trust this API?

Policies (like security, cookie, partner policies) communicate principles that specify the relation between customer and API supplier. Make this data accessible, findable and easy to navigate. Sidebar summaries can help to orient your users.

MVP and beyond

Rather than including all the documentation or content types we listed above at once, it is more important to:

  • Examine, but also align the information needs of your company’s key audiences with your developer portal strategy,
  • Adjust content to your users’ expectations logically and efficiently, decide what roles you want the content types to play in the user journey.

An MVP should focus on the minimal content that your users need to do their job. New information can be added later to address issues you discover in the developer journey as you keep evaluating and iterating on your developer experience (DX).

While there are best practices, it is impossible to create a great DX without iterating. Too much content can sometimes be as much a problem as too little content. This iterative nature of the whole process is another reason why a docs like code approach has become so popular in the API community.

Bare minimum MVP

As a bare minimum an MVP should provide the following information and corresponding minimum content:

 

alt

First iteration

A first iteration could have a blog to experiment with new content, and could provide extended support options:

alt

Second iteration

A second iteration could answer all 11 questions and provide exhaustive API documentation:

alt

MVPs and their role in the developer journey

How do the listed MVP and the subsequent iterations address the 6 stages of the downstream developer journey?

Minimal MVP

alt
With this minimal MVP, developer portals only address the discover/research, get started and develop/troubleshoot stages: users find an answer to what the portal is about, how they can get started coding and where to find the code.

First iteration

alt
This developer portal MVP already addresses 5 out of 6 stages in the developer journey, but with a limited number of documentation types. This kind of portal could provide a blog, but also support resources, like an FAQ page or a community forum. (Note that the content types that we added for this iteration are written in italic.)

Second iteration

alt
An example of how all the questions above can be translated into documentation types that do not only address all the stages of the developer journey but also focus on the developers’ different learning approaches more thoroughly. Some documentation types can appear in more than one stage of the journey. We also indicated some examples of subcomponents. (Note that the content types that we added for this iteration are underlined.)

 

alt
Self-service support is arguably the most important role of a developer portal: explore support resources.

 

Combine best practices with strategic decisions

Your developer portal is an interface for your API strategy, and, ideally, aligns the API communication with the documentation. That is why it is crucial to make a thorough study of your strategic objectives and the personas that will be interacting with your developer portal.

Would you like to get help developing your portal? Get in touch for a complementary Developer Portal Architecture Workshop or get a quote for a Content Architecture Workshop.

 

This post was written in collaboration with Kristof Van Tomme, whose “API docs bingo” talk at the API Platform Summit 2017 in Stockholm provided the idea and outline for this post.

Kathleen is an information architect helping clients find out how to align business goals and user needs with the knowledge we gathered about devportals. She grew her expertise through early research on developer portals to determine components, strategy, and best practices for user experience. She holds master's degrees in history and in archival science & records management.

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