The basics: “If you are unable to explain something in an accessible and inclusive way, then you don’t know it well enough.”
In this blog, we will explore different elements of accessible and inaccessible language, and will illustrate how you can apply this by editing an example.
What is inaccessible language
So what is an example of inaccessible language in the tech industry? You may have heard others in the industry refer to this as “tech bro” language. If this is a new term for you, another analogy would be to think about being a car fanatic -- or a “petrol head” as they call it in Top Gear. For those who are really into cars, they can skip the specifics about how an engine works and what specs make an engine a good one. Someone who knows nothing about cars may just want a simple pros and cons list to help them make a purchasing decision. For a “petrol head,” diving deeper into the specifics is useful and they don't need to start their research by covering the basics.
Things you should avoid:
Using technical terms without explaining them to your audience
Using buzz words
Preaching language⁽¹⁾ - i.e., why something is the best (according to you)
Preaching Language⁽¹⁾
To clear this up, it's important to try to steer clear of biases as much as possible. Of course, we naturally have these as humans, but showcasing numerous frameworks and approaches make for more inclusive writing.
Accessibility Exercise
Let's begin this exercise with an inaccessible block of text that we will rewrite to become more accessible. Feel free to grab a note book or open up your notes app to work on this exercise with me. We are going to list or underline the parts that require revision (or keep a list of things in your head, I know some of you are lazy like me 😉).
The original goal of this text is to sell a JavaScript framework to a developer who might be interested to use it. This is an example of a paragraph you could find in a top frameworks list.
This new amazing Isomorphic JS framework is, blazing fast, provides routing and XHR utilities. It supports all the browsers like IE9 without any poly-fills! You can use this tiny (6.9kb gzip) framework to talk to RESTful-, RPC- and SOAP- API’s without any hassle. This is accomplished by creating a layer between the native XML and Fetch. It is used by the FANG companies! The routing can be utilized in SPA’s, PWA’s and PMA’s with the V-DOM. You can use this to get your dev journey to the FIRE level! Specific for the back-end you can use SSR, CSR!
Try not to peek at the answers already -- I know this text is quite exaggerated. However, compiling this sample text didn’t take me more than a few minutes. These are real life examples of texts being used in the wild from various sources, all from Googling "what are the top 10 JavaScript frameworks?".
Accessibility Answers
Here is the inaccessible text again however I have highlighted the elements that where inaccessible for new developers.
This new amazing Isomorphic JS framework is, blazing fast, provides routing and XHR utilities. It supports all the browsers like IE9 without any poly-fills! You can use this tiny (6.9kb gzip) framework to talk to RESTful-, RPC- and SOAP- API’s without any hassle. This is accomplished by creating a layer between the native XML and Fetch. It is used by the FANG companies! The routing can be utilized in SPA’s, PWA’s and PMA’s with the V-DOM. You can use this to get your dev journey to the FIRE level! Specific for the back-end you can use SSR, CSR!
First of all, this text expects you to know certain words in the industry. A new developer looking to start with these frameworks would find this text completely inaccessible.
Isomorphic JS framework
Isomorphism as applied to web development means rendering pages on both the server and client side. It usually implies the use of JavaScript (JS) and Node.js / Io.js (both are a way to run JS outside the browser) because they allow for the re-use of libraries and frameworks (libraries / frameworks are peaces of code you can install or download in your code base so you don’t have to reinvent the wheel), allowing JavaScript code to be run in the back-end and front-end.
XHR utilities
So I looked at some paragraphs from different JS libraries/frameworks and found this. I added it in this example because I had to look up what it meant. And, I should note that I am proficient in JavaScript Development!
XHR stands for XMLHttpRequest. A way to talk to an Application Programming Interface (API), is a way for two or more computer programs to communicate with each other.
Utilities are usually functions to make your development easier.
IE9
Currently not really relevant any more since IE (Internet Explorer) was discontinued by Microsoft. 9 stands for that version and there were, in total, 11 versions usually noted as IE<version number>. I had a blast finding this since the list that I took this from was compiled after IE was discontinued.
poly-fills
A poly-fill is a piece of code that creates a functionality that the browser usually provides. However some functionalities are not available in older browsers that are still used today.
Continuing;
I could go over all the bold expressions in the example text and explain what they all do -- however, I think that you would have stopped reading by this stage. My point is that between the example text and these follow-up paragraphs, we already have a lot of explanation going on for only the first TWO sentences! So how do you strike the balance between being accessible, informative while still creating text that is legible and fun to read?
Accessibility rewriting
This new amazing JavaScript framework is fast and provides a new way to talk to your favorite Application Programming Interface connecting your code with your favorite applications! You won’t need to install other frameworks to make this work! It is light weight and wont slow down your website. It can be used anywhere you want that’s the power of example.js!
So in this first sentence I explain what an API does and I do not abbreviate it. I do not use fancy terms to tell what it can do but write that it can be used anywhere you want for what it was:
This is accomplished by creating a layer between the native XML and Fetch. It is used by the FANG companies! The routing can be utilized in SPA’s, PWA’s and PMA’s with the V-DOM. You can use this to get your dev journey to the FIRE level! Specific for the back-end you can use SSR, CSR!
To:
You won’t need to install other frameworks to make this work! It is light weight and wont slow down your website. It can be used anywhere you want that’s the power of example.js!
From what it was:
This new amazing Isomorphic JS framework is, blazing fast, provides routing and XHR utilities. It supports all the browsers like IE9 without any poly-fills! You can use this tiny (6.9kb gzip) framework
To:
You won’t need to install other frameworks to make this work! It is light weight and wont slow down your website.
Takeaway
Next time when you sit down to write a technical article for your audience, think about the following:
Will your reader understand what everything means?
Is this fancy word really required?
Keep It Stupid Simple (this is my own, more positive twist on the KISS principle).
That’s it for me! Have an amazing writing journey!
If you found this blog helpful and valuable please consider following me on Medium. I write about Agile, Inclusivity, Accessibility and other Tech related things.
This blog was original published on Medium by Tessa van Walstijn.