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.
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:
- What is this API?
- How do I get started with this API?
- What do I need to understand about this API?
- How do I get X done with this API?
- Do I know all the details of this API?
- How do I use your API in Y?
- Is somebody still working on this API?
- Where do I go when I have a problem with this API?
- How do I get access to this API?
- Can I afford this API?
- 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:
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)
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.
- 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.
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.
Explore the role of blogs in the developer journey.
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:
First iteration
A first iteration could have a blog to experiment with new content, and could provide extended support options:
Second iteration
A second iteration could answer all 11 questions and provide exhaustive API documentation:
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
First iteration
Second iteration
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.
