Developer Portals with Great API Docs
Breadcrumb
- Home
- PronovixBlog
- Developer Portals With Great API Docs
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.
This is a tooling-agnostic article. Are you looking for tools? Check our post on free and open source API documentation solutions.
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.
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 a developer portal and API documentation? Read our fellow tech writers' opinions in our post.
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:
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.
Want to read more on developer portal content types?
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:
[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!]
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:
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.
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.