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.
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).
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.
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:
- Introductory post
- Part 1: Overview pages
- Part 3: Guides and tutorials
- Part 4: Reference pages
- Part 5: FAQs, Forums and other Support Resources
- Part 6: Software Development Kits (SDKs)