Skip to main content
Information Architect
Jun 01, 2022

Efficiency, effectiveness and satisfaction define usability. A developer portal with frictionless user journeys and consistent API documentation will attract people who will generate traffic and revenue. However, in order to provide a better user experience you need to go beyond usability.

Early stage user engagement leads to community

The focus for this article is on individual users or a team of users who start driving adoption of your APIs through your developer portal. The more users become engaged the larger your group of users—your community—can become. Community engagement and developer relations can be a next step to focus on in your long term roadmap.

User Engagement

Efficiency, effectiveness and satisfaction define usability. A developer portal with frictionless user journeys and consistent API documentation will attract people who will generate traffic and revenue. However, to provide a better user experience you need to go beyond usability.

Enhanced engagement can help to:

  • define your partner strategy;
  • increase the range of use of your developer portal;
  • raise profit;
  • retain users and enable them to be successful, via:
    • functionality that makes user journeys as smooth as possible;
    • experience for the user to feel powerful, motivated and involved.

We previously wrote about engagement by following the six stages of the downstream developer journey. How can you inspire your users to return to your devportal? How to spur them to advocate for your portal?

In this post, we tackle engagement from a researcher’s point of view, and give practical examples of how to implement research findings on your developer portal. We outline how you can engage your users by incorporating engagement attributes right from the initial developer portal building phase.


Inspire, Educate, and Authorize

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?

Read more

What is engagement?

In their study on “The Development and Evaluation of a Survey to Measure User Engagement”, Heather L. O’Brien and Elaine G. Toms (2010) define engagement as something that goes beyond usability.

The study describes ten “engagement attributes” (as used in the initial stages of their research): aesthetics, affect, focused attention, challenge, control, feedback, interest, motivation, novelty, and perceived time. We have added an additional value pertaining to developer portals, the engagement attribute of support.

Engagement attributes on developer portals

How can we interpret these engagement attributes when applied to developer portals?

1. Aesthetics

Is the developer portal visually pleasing?

Well-done UI design increases clarity and trust. When executed consistently, it enhances the overall experience of the developer portal. 5 items to keep in mind regarding great devportal UI design:

  • Make sure that the design serves the content.
  • Reduce API friction through design that supports the content architecture.
  • Follow developer “culture” trends.
  • Bring harmony in the design of your marketing site and devportal.
  • Focus on consistency regarding the look and feel of your documentation components, landing pages, release notes etc.
Plaid was praised for the strong consistency and clarity of the UI and design, which is also extremely consistent with their corporate website. It’s easy to access the information that is needed to implement their APIs. (Plaid, winner of the Best Design category, DevPortal Awards 2021)

You can find more practical information on this topic in our DevPortal Design Guide series.

2. Affect

Do users feel emotionally involved?

To attach your developer community to your products and developer portal, it is important to engage and involve its members. You can motivate and attract by the following best practices:

  • Documentation: provide options to send in bug reports, to suggest edits, to share new solutions (you may even compensate users for providing tutorials for niche sections!).
  • Events, hackathons: organize meetings for the mutual benefit of your users and your organization.
  • Community pages: encourage and involve users, e.g. give them voting rights to show appreciation for peers and specific answers.
  • Try out & learning options: add a personal touch to your tutorials, e.g. TwilioQuest for learning Twilio.
Twilio Quest — Learn how to use Twilio in an nostalgic environment.


Twitter Developer Platform has a sheer number of community features (labs, local communities, encouraging the creation of own dedicated communities). It is part of their core business to connect people and make it easy to meet and exchange ideas, but the way they do it is special. (Twitter Developer Platform, winner of the Best Community Spotlight & Outreach DevPortal Awards 2021 category).

3. Focused attention

How focused are users along their journey?

We believe that focused attention (concentrating on one thing only) can be supported by an information architecture structure that incorporates the user’s requirements, and provides logical action steps, taking the user from A to Z.

A typical user journey of a developer that uses an API:

  1. Discover/Research
  2. Evaluate
  3. Get Started
  4. Develop & Troubleshoot
  5. Celebrate
  6. Maintain

4. Challenge

How difficult is it to perform tasks at hand?

Reduce API friction and obstacles along the different user journeys:

  • Make sure your main audience finds their way on your devportal easily through a straightforward navigation (e.g. top menu, sidebar with faceted search options, breadcrumbs).
  • Provide DX features that enable them to do their work faster (e.g. easy-to-handle registration process, “copy code” button, code language selector).

5. Control

Do users feel they are “in charge” over their experience?

Control is connected to trust. You will need to gain your users’ trust, if you expect personal data in return. Communicating correct and reliable information upfront is key when you want to build a “partnership” with your users.

Some examples:

When people can try out (parts of) your product beforehand, they will be more willing to give something in exchange for getting a concrete result. When all the information you provide must be behind a log-in wall, you could introduce a “staged registration process” and only ask for the amount of personal data that is in line with what they will receive.

Give users control by making sure they can update their profiles easily; provide quick access to and easy evaluation of legal data and security requirements.

GitLab provides an overview of what cookies they use and allow the users to agree or not.


User journeys can become complex (e.g. for billing processes): follow the mindset of your main audience.

Give people as much information as possible and as quickly as possible to be able to work with your offerings and maintain integrations. This way you can support their interaction with your devportal with status pages, API uptime/downtime details, versioning information and release notes, and by offering the option to receive updates and notifications.

A changelog indicates what changed and what will change (bunq Developer, finalist Best Overall DevPortal Award 2020).

6. Feedback

How do you gather feedback from users?

The response time and the quality of your answers to problems influence how people will experience your developer portal.

Examples for collecting feedback include:

  • contact forms with predefined fields that help people fill out what they would share or ask;
  • forums to exchange information among peers (when you have an active community);
  • rating systems that allow people to give their opinion quickly; and
  • targeted user research.
When rated too low, Twilio sends a message back with an invitation to discuss the issue.

7. Interest

Can main audiences find what they are interested in?

Conducting user research before setting up your devportal’s information architecture will warrant you to address the needs and interests of your main audiences. Think of providing user-focused homepage content, dedicated landing pages, information that serves both deeply technical and less technical users (e.g. via use cases or API summary pages).

8. Motivation

Are users motivated to proceed with activities on the devportal?

Inspire people so that they get motivated to work with your product. Our behaviour is driven by many factors.

  • Intrinsic factors drive you when you enjoy a task, you find a challenge fun, fascinating.
  • Extrinsic motivation urges you for example while doing something for winning financial or verbal appreciation.

The user’s context and background matters too, for example hobbyist or professional user, and what the urgency is of the task at hand.

A devportal can provide triggers to increase motivation from the very start, e.g. tools to make it easy to evaluate and test what is available before getting to a real-life environment.

9. Novelty

How “new” and “innovating” are the devportal features?

Unexpected novel features (exciters, delighters or attractive features as explained in the Kano Model) give us an experience of something we have not experienced before. However, these novelties will always become an expected feature over a time. For example, the once novel “API documentation is not only about API references” quickly became common practice within the world of developer portals.

Together with “Motivation”, “Novelty” is the category where elements such as product features play a major role in how likely we will recommend the devportal.

You can take care of DX throughout the whole developer journey, be it through simple solutions, creative innovations, well-executed existing technologies or interesting ways teach your various audiences how to use your products can already boost the experience of your users with the portal.

Always keep the “inclusivity factor” in mind and go beyond the basic expectations towards accessibility and localization.

The combination of an outstanding onboarding journey and the sophisticated e-learnings of Thingworx convinced the DPA jury to select them as a winner. (Thingworx, winner Best New DX Innovation category, DevPortal Awards 2021).

10. Perceived time

Can users correctly perceive the time that they need to get something done?

If you want to help people find answers to their problems, think how you can avoid frustrating them. They need to be able to get a task done, and to find the right information they need at the moment they need it. The theory is obvious but to put this in practice you need to think, analyze and iterate a lot.

  • Provide a clear overview of steps needed to get started.
  • Indicate response time for support queries or an approximation of the amount of time needed for feedback as applicable.
  • Be upfront in communicating about possible solutions and available programming languages.
  • Let your users think ahead by indicating pricing models in advance and make sure the first step is easy to take.
  • Consider highlighting important information to speed up coding: help users to learn and proceed quickly by matching explanations and code snippets in the API documentation.

11. Support

How fast and accurate is the information sent back to users? How can users support one another and be motivated to interact with peers?

The response time and the quality of your answers to problems influence how people will experience your developer portal.

Community pages, forums, etc can help users find answers to already raised questions, but also motivate its members to share solutions, interact with peers, and support others.

Note: the “support” attribute is not part of the original 10, but we think that providing well-working support options can enhance user engagement.

Measuring engagement as a KPI

We provided a few ideas on how you can go beyond usability by building in engagement attributes for your devportal strategy. Are you curious about how your users perceive your efforts? We are working on a questionnaire that will measure developer portal usability, engagement and trust that can be used to poll your developer community. Alternatively, you can ask us to conduct the questionnaire to get results from a large group of target developers. Interested? Contact us!


Many thanks to Szilvia Szalóki for her research on the topic, and to Laura Vass and Diliny Corlosquet for providing editorial feedback for the article!


Pronovix Logo

Are you building a developer portal? Interested in a shortcut? As a devportal company, Pronovix has created developer portals for 70+ customers since 2016. Talk with us to learn how our Zero Gravity developer portal can accelerate and simplify your launch.

Read More about our Devportal Solutions Contact us >

Kathleen is an information architect helping clients find out how to align business goals and user needs with the knowledge we gathered about devportals. She grew her expertise through early research on developer portals to determine components, strategy, and best practices for user experience. She holds master's degrees in history and in archival science & records management.


Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.