Is your developer portal accessible to all your potential visitors, all the way to the actual information they seek? Could it be more inclusive? Are you familiar with the Web Content Accessibility Guidelines?
In our previous article, we introduced the European Accessibility Act (EAA) which can change the web within the European Union from 2025. We also highlighted how cognitive accessibility has an impact on every user, regardless if they have any permanent, temporary, or situational limitations. Accessibility covers a wide range of fields, and this time, we focus on cognition. In this article, we deep-dive into developer portal content and bring simple practical suggestions.
Accessible developer portals
The four principles of websites' and mobile applications' accessibility (based on the DIRECTIVE (EU) 2019/882 OF THE EUROPEAN PARLIAMENT AND OF THE COUNCIL of 17 April 2019 on the accessibility requirements for products and services) are:
- Perceivability: information and user interface components must be presentable to users in ways they can perceive
- Operability: user interface components and navigation must be operable
- Understandability: information and the operation of the user interface must be understandable
- Robustness: the content must be robust enough to be interpreted reliably by a wide variety of user agents, including assistive technologies
How can a developer portal comply with the four accessibility principles?
- Perceivable: everything is available for more than one organ of sense, for example the information conveyed by an image is also available for screen readers in a text format
- Operable: all of the required interactions can be done easily on the interface
- Understandable: the information is written in plain English, the steps are easy to follow
- Robust: even if technologies are rapidly evolving, the content remains accessible and available
The Web Content Accessibility Guidelines (WCAG 2.2) show how we can avoid the barriers and help people with a wide range of disabilities. Based on WCAG 2.2 (WCAG 3.0 is coming soon), we previously collected some best practices for making developer portals more inclusive, so every user can navigate, interact with, and contribute to the website.
Digital Accessibility for Developer Portals: Interested in checking out part one of this series? In the previous article, we answer the question what is digital accessibility and why it is important for developer portals.
Designing Developer Portals for Digital Accessibility: Design an accessible—UX-first—devportal that supports your activities and enhances your brand image. This article outlines common sense and industry standards for the design and content of your devportal.
Guidelines to create accessible content
If every building block is inclusive, there is a higher chance that the sum of the elements will be accessible. Using this principle of bottom-up building, it is fruitful to keep in mind accessibility from the beginning. As Jennifer Riggins highlighted, accessibility is part of the developer experience, and it focuses on removing possible obstacles that can cause friction during the developers’ journey.
We recommend to consider the full spectrum of varying needs that is apparent in the population. For example, for someone with dyslexia (permanent limitation), it is challenging to scan a large body of text fast and effectively. At another place of the spectrum, if someone is in a hurry (situational limitation), they won’t have time for close reading.
Addressing the wide range of different cognitive abilities all at once, however, is a tough task. According to developer.mozilla.org, ‘one way to handle this is to focus on [the distinct] cognitive skills’:
- attention
- memory
- processing speed
- time management
- letters and language
- numbers, symbols, and math
- understanding and making choices.
Some content management systems (CMS) offer accessibility by default. For example, Drupal core has been an out-of-the-box accessible Open Source CMS for over a decade. As we previously highlighted, ‘Drupal 8 introduced extensive support for standard accessibility technologies including WAI-ARIA and semantic HTML5’. To improve the user experience, Drupal 8 and Drupal 9 use jQuery UI's autocomplete and modal dialogs, and provide the ability to change font sizes and color contrasts.
Drupal’s accessibility checker, Editoria11y is ‘a user-friendly, automatic checker designed to help authors create well-structured content with better text alternatives, without needing to remember to press a button or visit a dashboard’ just to mention an example from Drupal’s many possibilities.
A robust, well maintained and continuously evolving framework, such as the Drupal CMS, can save you a lot of work as you don’t have to reinvent already existing solutions. It can reduce cognitive load for your users, and offers a chance to avoid [potentially useless] one-of-a-kind creative efforts in the name of accessibility.
Best Practices
Some suggestions based on our readings, research, and experience:
- If one has limited prior knowledge on the topic, a clear structure and formatting can help them understand the documentation. Accessible headings are descriptive and provide an overview of the content that follows.
- If someone is in a hurry, they can scan through the text guided by the formatting (e.g. ordered or bulleted lists can help your users follow the required steps more easily, and breaking the text into smaller chunks instead of using wall of texts can also facilitate skimming the text).
- Regardless of the length, Funka's research project in Norway concluded that ‘too much information on the same page makes it difficult for users to find their way around and reduces their confidence in using the service (increasing stress).’ Try to keep balance among the amount of information, the examples, and the audiovisual guides.
- Remember that people have different proficiencies in different languages: plain English, and the simplified technical language, without using too much jargon helps understanding. Avoid using abbreviations and acronyms without explaining them first.
- Make information available for more than one organ of sense: everyone can benefit from captions on videos, written explanations under an image, or an audio file transcription.
- Using consistent navigation and breadcrumbs helps people find their way around your website much more easily (or if they forget what they worked on, the navigation bar could help them to remember). Using descriptive link texts that accurately describes the content of the page it directs the users to can also be helpful (instead of using non-descriptive links such as "click here").
Providing examples always makes it easier to understand how an API works.
W3.org also collected a few examples of how one can make their portal more accessible by focusing on eight major areas. They highlighted on their website:
- Help users understand what things are and how to use them: some people get easily disoriented on a website. Making it clear what things are and how to use them will result in a better user journey.
- Help your users find what they need: an easy to understand layout is crucial (e.g., search field, visual cues are effective) as users need to find what they are looking for quickly and smoothly.
- Use clear and understandable content: complex language and uncommon words can be a serious barrier. Short sentences, simple tense, and short blocks of texts are recommended.
- Help users avoid mistakes, and know how to correct them: try to avoid timeouts, and help the user notice form errors.
- Help your users focus: any content or elements that distract or interrupt users can disrupt the workflow.
- Ensure your processes do not rely on memory: try to avoid asking the users to remember numbers or passwords.
- Provide help and support: giving feedback and helping users when they have difficulties improves the user experience.
- Support adaptation and personalization: users should be able to use assistive technology (e.g., spell checkers, support for text-to-speech, etc.), add-ons and extensions.
Summary
Regardless of your developer portal’s maturity, we recommend regularly re-inspecting its content and layout for cognitive accessibility. Make digital content inclusive and accessible for a wide range of visitors, strive and learn to include everyone with empathy and understanding of permanent and situational barriers.
Where to start at all? Clear and concise structure and content will help guide users through your developer portal.
We continuously work on having a better understanding of the different ways in which users consume information and how we can help people get to the information they seek. If you need experienced help with your developer portal, we invite you to get in touch with us.
If you seek specialized assistance with your developer portal, and want to know how you could make your portal more accessible, reach out to us.
Resources and useful further readings
- A11y Project
- DIRECTIVE (EU) 2019/882 OF THE EUROPEAN PARLIAMENT AND OF THE COUNCIL of 17 April 2019 on the accessibility requirements for products and services
- WCAG 2.2
- #A11y: Accessibility Is Part of the Developer Experience
- developer.mozilla.org
- Drupal.org
- developers.google.com
- W3.org
- Digital Accessibility for Developer Portals
- Designing Developer Portals for Digital Accessibility
- Cognitive accessibility for developer portals: upcoming changes in the European Union
- Drupal for Developer Portals
- Cognitive accessibility tested in Norway
