Driving API adoption is crucial for a developer portal. In this post, we’ll explore how you can strengthen user engagement right from the very start of your API program regardless of whether you have a public-facing, partner or internal devportal. (Examples in this post are taken from public-facing devportals.)
Users, context and content are key
When we at Pronovix start working with a client, we usually conduct user research, compile a content inventory and look into the context of the API program. In short: we focus on the information architecture (IA) first. Nomen est omen: the main audience of developer portals are the developers, but our projects show that decision makers and business managers often play an equally important role.
- How can you integrate all your users’ needs into your portal?
- What are the jobs that a developer portal needs to fulfill?
- And how can those tasks enhance user engagement?
Inspire, educate, authorize
We believe that three concepts are key to strengthen user engagement:
These terms define the tasks of a developer portal and can also help us to create better user journeys.
Inspire
Build trust via quality
A well designed and actively maintained developer portal shows that an organization is investing in its APIs. This, in turn, helps convince developers that they can rely on both the portal and the organization behind it.
You can read more about trust and how it influences DX in one of our previous articles.
Quality developer portals are designed to be self-evident to use and to embody professionalism. Pay attention to the following:
- Communicate in an appropriate and clear way (e.g. via consistent terminology that you collect in a style guide).
- Ban typos, broken links and similar mistakes that could decrease credibility.
Make APIs findable
You know that searchable APIs save time and reduce frustration. Optimize findability:
- Implement a straightforward navigation system.
- Market your API products:
- Conduct SEO research (buy-in from the marketing department) and implement the results.
- Think about the following:
- What users do we target?
- Where will we put marketing related content?
- How will we represent our products on the devportal?
API governance is reflected on public-facing portals
Arnaud Lauret (APIDays Paris 2018 — API the Docs track) pointed out that API design cannot be consistent without clearly defined rules. Establishing, sharing, updating and controlling rules requires governance. Arnaud defines API governance as designer relations, training and coaching people, promoting a product, providing tools that make the whole process smooth and effortless. “Consistency is the primary goal of API governance”. Designing APIs with guidelines and standards in mind will make it easier for users to discover your APIs and recognize related processes on the developer portal.
Consistent API design will result in higher quality APIs.
Communicate with developers
Inspire your main audience: be transparent about business models and show what you offer. This way your users will be more likely to get interested in your APIs.
External content (written by people outside of your organization) can raise more trust than content written by your own organization, so connect to the rest of the web:
- Be present on social media, on review sites and on websites that provide the information developers are looking for (e.g. StackOverflow).
- Share reviews and user feedback from people outside of your organization:
- If you have a blog, think about interviewing clients and provide guest posts.
- Feature active users and let them tell why they like your devportal, e.g. on a community page.
Make sure your APIs, devportal and related programs get noticed:
- Organize events/hackathons to meet your users.
- Take part in competitions such as the DevPortal Awards, Best Public API, DevRel Awards.
Show that you actively maintain your devportal. Transparency is indispensable to gaining loyal users and you need to show them they can trust your API programme. Provide for example:
- a clear pricing model that sets the boundaries of API usage,
- a transparent versioning policy,
- regularly updated API documentation and legal information.
Invest in Developer Relations (DevRel) and community building. Matthew Revell and Carla Teixeira defined four archetypes of developer champion programmes: how to form a strategy to build community models? They introduce 4 solutions that address the devrel stages education, awareness, retention, and adoption.
Show uptime
The decision whether or not to expose your APIs’ uptime might depend on your internal politics. However you look at it, indicating that your APIs are reliable and available is a must when you want to acquire, convert and retain users. One of the most common solutions is a dedicated page where developers can check the current API status of the service or product they are working with.
Educate
Build trust
Users will arrive to your developer portal with a specific task at hand. It is important to provide the information they need at the right moment and to help them interpret and use that information.
- Be open about the boundaries of what you offer and what they can do with it.
- Be committed to helping your customers.
- Provide as much information about services or products as possible before you ask them to go through an authentication process.
- Inform your users about possible changes.
Provide documentation and support
Your devportal will most likely serve users with diverse knowledge-base and/or infrastructure, so strive, where possible, for more than one way to present information. You can for example include documentation components that address different learning approaches (video tutorials, sample code etc), or you can express the same information with alternate wording or formats (e.g. use cases, topic guides, blog articles, case studies).
The way you structure your documentation influences how your users will evaluate it. Provide a smooth learning experience. Ideally your documentation will explain everything your users need to know. But in case something goes wrong, you can make troubleshooting easier when you provide different support options. Think about:
- Organization driven support:
- Support that the organization’s team takes care of (e.g. chat, contact form)
- Self-service support (e.g. FAQ)
- Peer-to-peer support, via a community page or a discussion forum.
- Third-party resources, such as GitHub, Stackoverflow, community messaging channels.
Furthermore, think about:
- What documentation and content components do you definitely need from the start?
- Do you have a community that can populate your community page or discussion forum?
API governance
As pointed out above, training and coaching people is part of API governance. When people use your APIs in the right way, there will be less frustration.
Sell API products
Explore possibilities that help to market your API products, such as:
- featuring use cases that provide quick access to a “hello world” project,
- communicating business decisions and new features in blog posts.
Communicate with developers
Channels that encourage collaboration and direct communication (such as Slack) can help to connect to your developers and support them where possible. Organize and participate at conferences and other community events to introduce new ideas and upcoming plans.
API strategy
Let your API strategy become common knowledge for your target audiences. Talk about it in interviews or in blog articles. Inform your users about new directions your organization takes, bring out news on innovations.
Business model
Tell your users upfront what they get in return for committing themselves to a specific business model. A free programme can help them to get to know and engage with your products and services.
Versioning policy
An unclouded, crystal clear versioning policy can help your users understand and take into account what changes when and how.
Authorize
Build trust & provide controlled access
The reciprocity principle states that you need to give your users something before asking any data from them. In other words: your users will be more likely to go through a registration process and share personal information if they already trust your devportal to be beneficial. Some examples of what you could provide before asking your users to register:
- Evaluation tools such as samples, a demo, an API uptime status page, your versioning policy, code examples, release notes,
- Testing and try-out tools such as a sandbox environment, an API Explorer, mock APIs, a playground.
Based on our in-house research results that we conducted for previous blog posts, in the most common user registration process patterns (for public-facing developer portals) the user:
- is able to access all documentation and features without registering.
- gets try-out options before registration but access to documentation only after registration,
- gets free try-out options after registration/authorization,
- goes through a staged registration model (concrete: ask for a few data first, ask for more later). The registration status implies a specific authorization status. The ongoing authorization status defines the level of access to documentation and features.
We believe that registration and authorization can be decoupled as a strategy to build trust, which can result in more commitment towards your devportal. An example of a user flow process:
- The API provider gives at least some information from the very start, even before asking users to register.
- While they wait for authorization, users can try out products:
- Provide a list with useful links,
- Provide a mock API or sandbox environment.
- After account validation, users can enter the production stage.
This example above is not applicable in all cases: user flows depend on the specific business requirements. Some general tips, however, are to:
- ease even the most rigorous system by making the process as flexible as possible (e.g. make the waiting process shorter or provide new information in the in-between steps),
- provide some information upfront that answers the main questions of your users,
- make sure your users feel welcome in the system even when the security stakes are high.
Sell API products
The pyramid of trust shows us that users will only commit to an ongoing relationship (and accordingly, become a long-term client or partner) when processes are transparent and provide real value. For more information about how to implement trust elements into your developer portal, read our article on Frictionless Onboarding: Optimize DX on Developer Portals.
Communicate with developers
- Ask for feedback: how do they experience working with your product? What could be done better? What do they still miss?
- Ask them to help write documentation: can you involve your developers to write about specific use cases and examples?
Measure usability
- How do users move on your devportal in general? Do they go through journeys the way you imagined it? Measuring and analyzing the user flow can help to better the user experience (e.g. via tools like HotJar, Matomo and Usabilla etc).
- What is it users notice, what do they struggle with when working with a specific product or service? Collect qualitative feedback in addition to quantitative data. Measure specific product and service usage to e.g. find out how and when APIs perform according to set parameters.
Partner policy
Partner policies can set the boundaries for cooperation and business, raise trust and long-term commitment. Think about whether you will:
- treat all partners equally and open up about how that happens in practice as a marketing strategy (e.g. sharing business, pricing models and partner policies), or
- treat your partners individually and do not open up about the details.
A strategy driven devportal design to provide better user journeys
How to inspire, educate and authorize your users to convince them that they are on the devportal they need to be? We hope that the thoughts we gathered in this post can help you design a quality developer portal and organize user journeys accordingly.
Can we help you with finding the right direction for your API program? Contact us!
Developer Portal: Strategy Series, Part 1 Through this series of posts we aim to provide you with strategies for raising the standards of both internal or external developer portals.
