Posts in this series:
- Introductory post
- Analyzing the API Docs and DX Patterns in the Best Banking Developer Portals
- Analyzing the API Docs and DX Patterns in the Best FinTech Developer Portals
- Analyzing the API Docs and DX Patterns in the Best Telecommunication Developer Portals
- Analyzing the API Docs and DX Patterns in the Best Media Developer Portals
- Analyzing the API Docs and DX Patterns in the Best Media Developer Portals 2
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.
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 a developer portal and API documentation? Read our fellow tech writers' opinions in our post.
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.
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.
- Academic research:
- Meng et al.: Application Programming Interface Documentation - What Do Software Developers Want?, Journal of Technical Writing and Communication, Jul 2017.
- Blog posts:
- Diána Lakatos: The Ten Essentials for Good API Documentation, Ten Extras for Great API Documentation, A List Apart, Sep/Nov 2017.
- Surveys:
- StackOverflow Developer Survey 2018,
- StackOverflow Developer Survey 2017,
- Smartbear The State of API 2016.
- Talks:
- Ashley Hathaway: The Art of Documentation & Making Your API Go from Good to Great, Nordic APIs Platform Summit 2017,
- Stephanie Steinhardt: API Documentation: what we can learn from developers, Technical Communication UK Conference 2017.
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:
- Introductory post
- Analyzing the API Docs and DX Patterns in the Best Banking Developer Portals
- Analyzing the API Docs and DX Patterns in the Best FinTech Developer Portals
- Analyzing the API Docs and DX Patterns in the Best Telecommunication Developer Portals
- Analyzing the API Docs and DX Patterns in the Best Media Developer Portals
-
Analyzing the API Docs and DX Patterns in the Best Media Developer Portals 2
