Skip to main content

Best Accessible Devportal

Information Architect
Jul 17, 2020

This article describes the Best Accessible Devportal award category for the annual DevPortal Awards.

In her talk on How privilege defines performance, Tatiana Mac points out the following: “In theory, web performance, accessibility, and inclusive design all have similar goals: provide the best, most consistent experience to all people using the minimal amount of resources.”

According to the Web Accessibility Initiative (WAI), inclusivity is about diversity, and ensuring the involvement of everyone to the greatest extent possible. It is closely related to accessibility (boundless experiences like understanding, navigating, interacting and contributing) and usability (effective, efficient and satisfying products).

This article collects various explanations, tricks and tools that enable inclusivity in the broad sense.

Best accessible portal

“Devportals that make their APIs and documentation accessible to all possible users, regardless of disability type or severity of impairment.”

But accessibility (sometimes referred to as A11y) on devportals is also more than that. It is about making your APIs, their documentation and all related information available for all possible audiences. “Understanding accessibility means we can build services that work for everyone, whatever their access need.”

Access for everybody — who is everybody?

The Write the Docs London meetup group had two sessions on accessibility in early May 2019 (we highly recommend watching the recordings: Tales of a keyboard-only user and You don’t know your audience). A striking takeaway was that you don’t need to find out what particular kind of impairments your audience suffers from: your audience is already diverse in multitudes of dimensions, some permanent, some situational. Design and write in a way that is valid semantic consumable for everyone. Do not force users to ask you for changes so they can access your content: those who do not immediately go to another site deserve your consideration before they even visit your portal. Make your devportal content seamlessly accessible for all methods of consumption.

Accessibility benefits people with and without disabilities

The A11Y Project lists the following categories of accessibility:

  • visual,
  • auditory,
  • motor,
  • cognitive, and
  • temporary disabilities, e.g. users with an arm injury.

The WAI furthermore includes:

  • neurological,
  • physical, and
  • speech disabilities.

They also point out that people without impairments can also benefit greatly from web accessibility, think of, for example:

  • small screen users,
  • older people with changing abilities,
  • situational limitations like too much sunlight or a stressful event, and
  • slow or limited internet connection.

Tips and tools

Explore the W3C list of best practices for spec developers.

The A11Y Project and WAI list a lot of guidelines, standards and tips, and some more came up while we did the research for this article. We think there is much much more. Please drop us a line if you know about further resources.

Designing for accessibility

The UK Home Office provides a set of excellent guidelines on the main dos and don’ts when designing for accessibility for users:

  • on the autistic spectrum,
  • of screen readers,
  • with low vision,
  • with physical or motor disabilities,
  • who are hard of hearing or deaf,
  • with dyslexia, and
  • with anxiety.
Pipedrive buttons and explanations
Descriptive buttons help users on the autistic spectrum (Pipedrive developer portal)

Increasing readability

An initiative that helps to enhance usability among your audience is the (evolving) readability guidelines project: “with guidelines for creating easy to comprehend content, we’ll design inclusively by default”.

Writing simple is hard. Hemingway Editor can help you to decide how complicated your sentences are.

The Hemingway Editor's analysis of a piece of text
Running the subtitle on Typeform’s overview page through the Hemingway Editor.

Tools to check accessibility

The WAI list on how to select a web accessibility evaluation tool can help you decide on the right tool to check accessibility based on provided features.

When screening for accessibility, you could try the following tools for free:

TomTom's overview page analysed by Color Oracle
TomTom’s overview page tested for deuteranopia via Color Oracle.

Provide better accessibility through various learning options

Thorough knowledge about your users is indispensable to provide good UX. The following are some additional thoughts around how people learn and how to provide appropriate content to support different learning paths.

When approaching a new API, some developers tend to learn concepts first (concept-oriented learners), others jump into the code directly (code-oriented learners). It is important to provide API documentation that support both learning strategies.

At the Chicago API the Docs conference, Shy Ruparel looked at learning approaches from another angle: you can, he said, support different ways of learning by providing the right documentation form.

  • Writing learners benefit most from traditional documentation (written sources).
  • Visual learners will want to visualize what and how things can be done. Provide charts, gifs, and video tutorials.
  • Auditory learners learn by hearing, e.g. through podcasts and recordings.
  • Kinaesthetic learners learn new things by experimenting and poking around: provide ways to grab their attention.
A tutorial page on Nexmo's developer portal
Nexmo (Vonage) provides tutorials with text, visuals and code snippets.

Overall, accessibility is crucial when you want to be dedicated to your users: showing that you care about them will send a strong trust signal that can evoke audience engagement and involvement over the long run.

The examples in this post are taken from some of the previous DevPortal Awards nominees and winners.

Developer Portal Categories

The Best Developer Portals Learn more about the award categories for the Developer Portal Awards and how you can submit a nomination.

Read more »


More on accessibility

All Pronovix publications are the fruit of a team effort, enabled by the research and collective knowledge of the entire Pronovix team. Our ideas and experiences are greatly shaped by our clients and the communities we participate in.

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.