Posts in this series:

This series will focus on finding the best, most innovative and interesting practices on existing developer portals independently of their toolchain.

While we can see immense differences in how companies organize the API docs on their developer portal, some provide us with great examples on how documentation can add to the developer experience.

What do developers expect of documentation nowadays? How do exemplary portals anticipate on those expectations? To explore this, we will look at 30+ public developer portals (of companies in various industries) and check how they make use of the insights of recently published academic research results, blog posts, surveys and talks.

Free and open source API documentation tools

This is a tooling-agnostic article. Are you looking for tools? Check our post on free and open source API documentation solutions.

Read more

Each post in this series will feature one public developer documentation portal category and focus on sharp ideas and solutions about the

In this introductory post we would like to provide some background to what we mean by these concepts.

What is a developer portal?

A developer portal is a well set table for API documentation with all the decoration that contributes to a complete experience for its possible users. It does more than simply collecting resources - it puts the various information in a complex structure that helps users navigate exactly to the part they need. As opposed to mere reference documentation, an API's developer portal can pay attention to all the possible audiences of the API product(s) that visit the developer portal for different reasons. It can, on one hand, address all the stakeholders, not just the implementing developers: consider CXO, decision makers and product owners. On the other hand, it can guide visitors to the milestone that best fits their current needs.

What is the Difference Between API Documentation and a Developer Portal?

What is the difference between a developer portal and API documentation? Read our fellow tech writers' opinions in our post.

Read more

Information sources about the API

Content and tools that help to evaluate and implement your API are indispensable to serve your developers’ needs along their user journey. There are several possibilities to translate the developers’ questions into documentation components and API related information sources. Some examples:

  • overview pages,
  • the “typical” API documentation components (such as tutorials, guides, reference documentation),
  • glossaries and conceptual documentation,
  • authentication and authorization process related information,
  • legal documentation (policies and terms of use),
  • support and help resources (FAQs, forums),
  • third-party resources (GitHub, StackOverflow),
  • libraries, frameworks, platforms, SDKs,
  • blogs,
  • use cases, case studies, worked examples,
  • prototype building options.

In this series of posts, we will be looking at what type of content the API developer portals provide to tackle, both directly and indirectly, their users' needs.

cover image blogs

Want to read more on developer portal content types?

A checklist for quality API docs

API documentation needs to build trust. An evident criterion is up-to-date, complete and reliable information that is easy to find. The posts, articles and studies we analyzed for this series show that developers value most if the API documentation is:

  • Interactive: e.g. is there an interactive section to the developer portal where it is possible to test the documentation?
  • Readable and consumable: e.g. what knowledge level of English is needed to understand the documentation? Is there a possibility to change the language settings?
  • Easy to find and search: e.g. via the presence of a search bar, tags, filtered search options.
  • There is information on the service – reliability, scalability, performance: e.g. an API status page, a changelog, information on pricing models.
  • Responsive: Do the pages render well on various devices?

[Note: Some of the above listed items have a web design component. We are working on a series about dev portal design, stay tuned via our newsletter!]

References and portals in this series

We would like to thank the authors of the following articles, posts and talks for providing great inspiration and essential background material for this series.

For our analyses, we chose companies with public developer portals in various industries. Subscribe to our newsletter to be among the first to read about how companies like ABN Amro, Adyen, Algolia, Braintree, CenturyLink, GitLab, Heroku, Mailgun, Microsoft Windows, PayPal, Slack, Spotify, Trello and Twitter (and many more) treat API documentation and provide their users with practical and up-to-date solutions!

Many thanks to Laura Vass for the editing!

Posts in this series:

About the author

Kathleen De Roo

Information Architect, Technical Content Writer

Kathleen started as a technical content writer, responsible for doing research and writing on developer portal aspects. As an information architect, she helps clients find out how to align business goals and user needs with the knowledge we gathered about devportals.

She holds master's degrees in history and in archival science & records management.