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.

Enhanced engagement can help to:

  • Build out your partner strategy.
  • Increase the range of use of your developer portal.
  • Raise profit.
  • Retain users and enable them to be successful, via:
    • Concrete tools that make user journeys as smooth as possible.
    • Providing triggers 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.

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.

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.

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 that provides logical action steps, taking the user from A to Z.

The typical user journey of a developer that uses the API.

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 behind the scenes can become complex (e.g. billing processes). Tackle expectations with dashboards that follow the mindset of your main audience.

Give people as much information as possible and as quickly as possible to be able to maintain integrations. This way you can oversee 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.

6. Feedback

How fast and accurate is the information sent back to users?

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

Best practices 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.

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 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 so as not to be punished, or for winning financial or verbal appreciation.

The user's context and background matters too, for example hobbyist or professional user, what is the urgency 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 user experience 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 to teach your various audiences how to use your products.

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

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.

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!



About the author

Kathleen De Roo

Information Architect, Technical Content Writer

Kathleen started as a technical content writer, responsible for doing research and writing on developer portal aspects. As an information architect, she helps clients find out how to align business goals and user needs with the knowledge we gathered about devportals.

She holds master's degrees in history and in archival science & records management.