This is the second post in our developer portal components series about documentation patterns. Make sure to subscribe to our mailing list!

The onboarding page, a crucial component for developer portals

Developer experience on first contact is arguably the single most important job of a developer portal. In some cases your API might only have a few minutes to hook a developer, if it isn’t immediately clear where developers can start their integration efforts, they might leave and never come back. This is why onboarding pages are so important. In this article we’ll list the various roles onboarding pages need to fulfill. We’ll also explore how the developer portals we reviewed expose them and how they are labeled.

Different onboarding for different audiences

Depending on the objective and the prior experience of a user, an onboarding page needs to fulfill 3 different roles:

  • Evaluate: Help developers and managers decide if your API will have all the necessary features for the implementation they are planning.
  • Educate: You should never assume that a developer will have a full understanding of the industry. A developer might not be familiar with some of the domain language (professional vocabulary used in an industry) you are familiar with (e.g. “dunning” in recurring payments). But developers will, at least initially, not know what they don’t know, so they will not start reading your thesaurus. In his Write the Docs talk, Michael Meng reported on the findings from his research with Andreas Schubert and Stephanie Steinhardt. In their research they found that the inclusion of conceptual documentation in onboarding materials might help speed up developers.
  • Accelerate: The most obvious function of onboarding materials is to give developers a clear list of all the steps that need to be taken to make a complete and proper integration. Code samples in onboarding materials can also help developers avoid common pitfalls.

Onboarding in the developer portal’s information architecture

Ideally, the overview page (e.g. frontpage or API product landing page) should provide a link to the onboarding page. In our research 8 (out of 12 developer portals) had the onboarding documentation as a main component on their overview pages.

  • Most of the overview pages in our research treated onboarding documentation (quickstart, getting started, basics, …) as a main component.
  • 2 sites (DigitalOcean, Dwolla) labeled it as a subcomponent of “guides”: the onboarding documentation itself was not represented on the overview page.
  • IBM Cloudant had 2 overview pages: a docs overview page and a “for developers” overview page. Both pages contained onboarding terms that linked to several subpages: "Getting started" in the footer linked to Guides; "Learning Center" had a getting started topic; "Cloudant Basics" contained introductory information.
  • Apigee’s docs overview page hid the onboarding documentation in the sidebar menu grouped under their respective product sections.


Example of a Quickstart guide component on Keen IO’s overview page (Keen IO)



How to call your onboarding section

“Get started” is a widely used term. We noticed two customs:

  • Get started = The how-to-start guide. The developer portals we researched used quickstarts, guide, get started, basics, getting started and walkthroughs mostly to refer to a beginner’s guide or introductory article(s) and rarely to describe in-depth articles.
  • Get started = The call-to-action (CTA) button (refers to subpage).

Onboarding subcomponents

The formats of the onboarding documentation differed. We found:

  • Questions and answers that explain basic facts about the API;
  • Videos that engage your users visually;
  • Introductory and/or in-depth articles describing the company, API and/or used terminology;
  • In Real Life examples;
  • Code snippets to help developers get acquainted with your API product.


Example of “Get started” as a CTA button and “Quickstarts” as a how-to-start guide - note how the text also starts with “get started” (Twilio overview page)



Example of a Quickstart guide with code snippets (Keen.io)



Example of a Getting started with code snippets (Dwolla)



Example of clearly indicated basic information about specific Cloudant terminology (“Basics”, IBM Cloudant)



Example of Getting started used as a general term for introductory (“Overview”) and in-depth articles (with or without code) (Asana)

Onboarding best practices

Onboarding documentation is an essential part of a developer portal. Main tips:

  • Treat onboarding documentation as a main component on your overview page.
  • Keep in mind what the onboarding documentation should cover (introductory information, in-depth documentation) and
  • choose your terminology accordingly. Use obvious titles: developers should get the meaning immediately.
    • CTA text alternatives for Getting started could be Learn more or View.
    • Differentiate between an introductory article about the product and a real how-to-start guide with code snippets by using:
      • Getting started guide, how-to-start guide, quickstart guide or onboarding guide solely for explaining core features (including code snippets) and
      • Introduction or Basics for general information in a nutshell (eg. about specific words used for the API of a certain company), in plain English. We do not recommend the term Overview for short introductions, in order not to confuse it with the overview page of the developer portal.
  • Test your assumptions about labeling and validate your user experience. Read up on UX and DX research to do this yourself, work with a contractor to avoid familiarity bias, or contact us - we are setting up a procedure and a team specifically to evaluate developer experience on developer portals.



Note: in this post, we focussed on onboarding documentation. We found, however, that specific site builders also treated tutorials as “getting started” topics or the other way round, others put onboarding documentation in the category of “Guides” on the overview page. More on that next week.

The research we referred to from Professor Meng’s group still needs to be published, but you can watch his talk at Write the Docs Prague on YouTube.

For further information on improving API documentation terminology: check API Documentation with meaningful names by Jan Christian Krause and his talk at Write the Docs Prague.

Many thanks to my colleague Kristof for co-authoring, reviewing and sharing his thoughts on this topic.



Other posts in this series:



About the author

Kathleen De Roo

Copywriter

As a copywriter and member of the content team, Kathleen is responsible for writing, reviewing and editing website copy and blog posts. She has an interest in Information Architecture.

She holds master's degrees in History and in Archiving / Records Management. Before joining Pronovix, she gained professional experience in teaching and office management and was a volunteer for several non-profit organizations.