DevPortal Awards 2019 is open for nominations, with two new categories. We are looking forward to hearing what you think are the outstanding API developer portals and why you think so.
This is the first article in a series that serves with background explanations and examples within the categories:
- we'll give you an overview of the different nomination categories and
- walk you through the evaluation criteria to see where your devportal excels.
Posts in this series:
- Best Accessible Devportal and Best Internationalized & Localized Devportal
- Best API Business Model and Best Decision Maker Documentation
- Best Onboarding and Best API Reference Documentation
- Best DX Innovation, Best Design, and Best Overall Devportal
Why these new categories?
This post will focus on the two new DevPortal Awards categories we launch: Best Accessible Devportal and Best International & Localized Devportal.
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).
Throughout our developer portals research and project work we’ve done so far, we found that companies often address audiences with specific expectations in various regions. When you pay attention to accessibility, internationalization & localization elements, the overall user experience will be better and your users will be more likely to engage with your devportal.
This article collects various explanations, tricks and tools that enable inclusivity in the broad sense. The examples in this post are taken from some of the DevPortal Awards 2018 nominees.
Best accessible portal
Our DevPortal Awards 2019 definition for this category: “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:
- cognitive, and
- temporary disabilities, e.g. users with an arm injury.
The WAI furthermore includes:
- 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
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.
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.
Tools to check accessibility
The WAI list on how to select a web accessibility evaluation tool 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:
- WebAim’s tool to evaluate web accessibility: discover accessibility issues on specific pages.
- Color Oracle: color blindness simulator.
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.
- 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.
Best international & localized portal
Our DevPortal Awards 2019 definition for this category: “Devportals that implement devices or content strategies to address topics like cultural diversity, differences in language capabilities, local legal requirements and regional expectations.”
According to Wikipedia, internationalization (I18n) is the process of designing a software application so that it can be adapted to various languages and regions without engineering changes. Localization (L10n) is the process of adapting internationalized software for a specific region or language by translating text and adding locale-specific components. In short: internationalization — with its design and development practices — enables localization for target audiences that vary in culture, region, or language.
Cultural diversity & language capabilities
In her article on the role that UX writers play in localizing a regional product, the author states that “it’s more than just writing with correct grammar, it’s truly about using words that people can identify with.'' Some of the listed tips:
- Adopt language inclusivity (avoid jargon, slang or idioms, and use gender-neutral pronouns).
- Use the 30% rule for interface copy (some words become longer after translation: consider this in the UI design phase).
- Build a team of content reviewers that are familiar with the language, specific user needs and the cultural habits.
Localization is more than translating and updating existing content: it aims at adapting a product, application or content to the language, cultural and other requirements of a specific target market, the “locale”. It might require the rethinking of logic and visual design. Localization can involve customization connected to:
- Numeric, date and time formats
- Use of currency
- Keyboard usage
- Collation and sorting
- Symbols, icons and colors
At the API the Docs London 2018 conference, Atsushi Nakatsugawa illustrated what the benefits of localization are versus translation.
Local legal requirements & regional expectations
What do you need to run a global API business? You translate or localize content, and also:
- Prevent misinterpretations and avoid content that users might consider as sensitive or inappropriate.
- Pay attention to regional legal requirements (e.g. some regions don’t allow deep linking).
- Take regional business restrictions into account.
- Research local user expectations: this will influence your devportal’s ideal UX accordingly.
Tips & tools
- Explore the W3C list of best practices for spec developers and the short I18n review checklist.
- The W3C Internationalization Checker helps you find out to what extent the web page you enter is internationalization-friendly.
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.
Know any other tips and tricks to boost inclusivity? Let us know!
DevPortal Awards 2019: How to nominate your developer portal
What is the goal of the DevPortal Awards?
The goal is to recognize public-facing developer portals that show great examples in eleven different categories and to find the developer portal that provides the best overall experience.
Why should I nominate my developer portal?
By nominating a portal you can draw the community’s attention to it and acknowledge the work of the people behind it.
How can I nominate my devportal?
Please fill out the nomination form!
Who chooses the winners?
The winners of the 11 nomination categories will be chosen by the Awards Jury in October. In the Best Overall Developer Portal category two winners will be selected: one by the jury and one by the community via public voting. The portals nominated in any of the 11 categories are running for the Best Overall portal automatically.
How can I stay up-to-date and get notifications?
Sign-up to the DevPortal Awards newsletter and receive info on nomination and voting, nominee and jury news, and details on the gala event.