With the rise of web APIs developer portals have become an important subtype of websites. While developer portals always target a comparable audience (developers) and need to achieve comparable outcomes, it is remarkable how different most popular portals are.

We conducted an in-depth information architecture study of the documentation types used on developer portals searching for patterns. This is the introduction to a 6 part series in which we want to make an attempt at extracting best practices. The next weeks we’ll share with you what we discovered.

In our series we'll give a thorough overview of the documentation components used on Developer Portals. For a general introduction and for more information about developer experience check out the following blogposts:

We started our research with browsing through a selection of 30 developer portals that were ranked based on documentation characteristics. We selected 10 sites (Twilio, Digital Ocean, CenturyLink, Mashape, Apigee, IBM Cloudant, Keen IO, Asana, Mattermark, Dwolla). Looking at architectural components (place of documentation categories on site), there weren’t any patterns. But we did find similarities in structural design and in terminology.

We will focus on documentational categories, terminology, structural patterns, not on the content itself. Our purpose is to offer ideas and insights, share what we noticed and learned.

Defining documentation and its components

The words docs and documentation often cover different parts of the developer portal. A few examples:

For this series, we wanted to find one definition for documentation. Docs is the abbreviation of documents, written representations of thoughts. We define documentation as a set of documents. Documentation is every bit of information that documents the product of the developer portal, the API.

To be able to sort the various documentation types we detected, we categorized them into components. We defined these components with the help of the guidelines in the above mentioned blogposts and we completed these definitions with in-house site architecture knowledge. “Primary components” will stand for components represented on the Overview pages: Getting started-onboarding pages, Reference pages, Guides, FAQ pages, Example pages and Tutorials, while we will refer to topics like support, libraries, SDKs, integrations etc. as “secondary components”. Each developer portal we researched used the above mentioned components - rarely all, but at least a few.

Table representing how primary and secondary components will be categorized in this blogpost series

Overview of the posts in this series:

I’d like to thank my colleagues Kristof and Kata for ideating and discussing this research with me.

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.