What features of a developer portal can be used for frictionless onboarding and success in developer adoption?
Consider the two typical streams of onboarding users to your developer portal
- Downstream (consumer) journey: developers and decision makers who use the devportal to source APIs and product solutions
- Upstream (creator) journey: developers, decision makers, and content editors who populate the devportal with its APIs, product solutions, and documentation
This article outlines how the features of the Zero Gravity developer portals, from Pronovix, contribute to frictionless onboarding and success in developer adoption.
ownstream (consumer) Journey
1. Facilitate/Guide the steps your developers take to register and to get started.
Zero Gravity developer portals provide the ability to guide a user during registration and onboarding. Onboarding includes reading the fine print or at least accepting the terms and conditions offered by your developer portal, potentially confirming an identity with an email address, or utilizing your company’s single sign on (SSO). Where applicable, we layout the steps necessary for an easy predetermined path.
When a user registers on your devportal we can redirect them to the next step where they can take action. For example, while waiting for identity confirmation, we can point the user at a list of the most accessed APIs that they can ‘try out’ while waiting for their registration to be confirmed/completed. If an SSO user belongs to a specific group, we can direct them to that group’s predefined start point.
2. Developers can visualize and explore the API specification.
Zero Gravity developer portals generate API reference pages by uploading Swagger 2.0 or OpenAPI 3.0 files either manually or programmatically. The API reference UI can use either Swagger UI or alternatively Redoc for visualizations. The devportal also uses OAS visualization to adjust styling for customer specific branding within the devportal context. End users access a page with a nice and clear design with all the necessary functionalities like a try-it-out option. A developer can discover and research the API via code visualization & sample code.
3. There is a clear context for receiving supporting documentation.
API Reference documentation/technical documentation is not enough. The Zero Gravity developer portals expand the potential reference documentation to include supporting pages such as release note, legal documentation, and a business landing page for APIs. The latter explains the benefits and features of an API to business personas or to developers who are exploring the business value of your APIs. With this structure in place, it becomes easy to find SDKs, use cases, case studies, examples, API overview pages, and tutorials.
4. The right tools are available to improve discoverability of APIs and product solutions.
Your ability to discover APIs depends on the number of APIs being showcased and their available documentation. Most often a basic search of the API reference pages that includes some filters is sufficient to find your API.
The Zero Gravity developer portals also provide an API Catalog for a survey listing of APIs and solutions by category. Use cases that orient the audience to the affordances of an API or group of APIs, can also be created and promoted via the devportal blog or exposed using Zero Gravity's page builder.
For the cases where there is a vast library of APIs or solutions with sometimes questionable documentation lacking discoverability, we provide several potential options such as advanced search (of the entire developer portal), targeted API catalog search, or even an API explorer. The API explorer is used in the context of technical documentation to discover corresponding APIs via keywords, categorization, or grouped within a project.
More options for discovering APIs, products, and solutions keeps the devportal from becoming an API Freezer.
5. The processes for requesting or finding support are straight forward.
Not all developers or visitors to a devportal are expert on your product and offerings. At the same time, not all of our API customers need to provide the same level of support to their users. There are several options available in the Zero Gravity developer portals to facilitate your support processes via multiple options such as a Help Center, FAQ, or a Flexible Contact Form. In addition we recognize that there are cases when these are not flat pages but interactive experiences, such as a topic driven experience.
Upstream (creator) Journey
1. A user guide provides a quick-start to internal onboarding.
The user guide’s purpose is to help content creators and upstream developers make the most of the Zero Gravity developer portals’ potential. The user guide walks people through the devportal’s features with consideration for different learning and reading habits. The user guide focuses on content management and common scenarios. Where applicable, the user guide goes into step-by-step instructions via tutorials or how-tos. It includes an FAQ with suggestions for best practices for content management and basic site configuration.
The user guide is an ideal starting point to learn how to use Zero Gravity developer portals, how to implement API reference documentation, or connect supporting documentation. The user guide also details how to manage users and content items. The user guide is kept up-to-date by the Pronovix Technical Writer team.
The user guide is key to avoid becoming a tyrannical toolchain.
2. A flexible authoring experience configured for upstream developers and content editors.
Your technical documentation can be updated during continuous integration/continuous deployment (CI/CD) cycles with a docs-as-code development process. All other documentation is populated through basic publishing workflows. The Zero Gravity developer portals provide site administrators (or a group of users with access) with the ability to create, edit, or delete content. Basic publishing workflows support your company’s review process by providing draft or published states for content. Version control also gives the benefit of restoring previous content as needed. Further, the documentation structure provided for supporting documentation prompts people to follow your company’s guidelines for governance practices.
Keeping your devportal content up-to-date is vital to avoid becoming an API ghost town.
3. Place the user's focus on where they need to be.
Zero Gravity developer portals can mimic the business unit structure of your organization so that people, within the context of a business unit or group, can be positioned to first access the APIs and products most relevant to them.
4. A developer portal that adapts and innovates to reduce friction within your API program over time.
We know that people prefer to work within their existing/familiar information contexts. Doing so can improve upstream developer adoption of the devportal.
- Developers can make use of a sandbox environment to "kick the tires".
- Use of CI/CD with docs-as-code to keep technical documentation up-to-date.
- To reduce the friction for upstream developers we developed a means of providing a way to link Postman projects to API products within your devportal.
- Analytics to improve SEO and monitor the success of your API products
- Integration with API gateway management platforms (e.g. Apigee Edge, Apigee Monetization, Apigee Teams, Apigee Multi-orgs)
- Technical writers and content editors can work independently from developer processes to populate supportive documentation in real time.
- Product owners and decision makers have oversight of the big picture.
Why these features are important for Developer Adoption and Onboarding
We have published many articles that contribute to the features outlined above for the Zero Gravity developer portal. Inspiration for this article was prompted by James Messinger's article in Better Practices on How to Win at Developer Adoption when you only have a few minutes to impress.
Diliny is a Senior Business Product Manager at Pronovix. She focuses on understanding the capabilities of developer portals. Diliny carries out a wide array of research on topics centered on developer portals and the needs of API Teams who manage them. She holds two master’s degrees in Chemical Engineering and Science.