The tech-writers’ journal #3— Writing Inclusive Documentation
By: Amrithaa Sneha
Tags: Technical Writing, Diversity In Tech, Documentation, Developer Experience, Inclusion

Photo by Nathan Dumlao on Unsplash

In this article, we are going to discuss “Writing Inclusive Documentation. “ As tech writers, we get carried away in the process of breaking down a technical concept and delivering it in an easy-to-understand fashion, to an extent that we usually tend to forget the importance of the language used in the documents. Ensuring that our language is inclusive and empathetic is just as crucial as making sure the content delivered is accurate.

What is inclusive documentation?

In a nutshell, an inclusive document is one that takes into account all of its users regardless of gender, cultural background, physical ability, gender, and so on.

Why does it matter?

To make your users feel at ease

As tech writers, we need to make the readers feel at ease and included when they read our documents. The documentation we are writing must appeal to a wide range of audiences. We might be documenting some complex DevOps concept, but our audience can be anyone; even a front-end engineer who only wants to learn this one concept. It is therefore necessary to keep in mind the wide spectrum of audience.

Our language influences our thought process

Languages have the power to shape the way you think, so the words we choose matter. This is a fairly new thesis by a cognitive scientist Lera Boroditsky and her team. Don’t believe me? Check out the Ted talk yourself:

How to draft inclusive documents?

There are multiple layers to creating inclusive documents. In this article, we shall try to peel off a few of them.

Write gender-neutral documents

Holding it gender-neutral is one way to keep the audience from being excluded. Using a second person (you, your, yours) is a perfect way to promote a sense of interaction with the audience. This technique is highly effective since the reader feels like they are being addressed directly.

Avoid racially loaded terms

Words such as “slave-master” are generally used to describe technical relationships and they bear a fair amount of historical baggage. Consciously choosing to use such potentially offensive terminologies sends out a strong message about the culture in your organization. Some alternatives include “Primary and secondary,” “Primary and replica,” and “Source and sink.”

Be more empathetic

One of the key ways to show developers that we care, is to choose a documentation style that curates a smooth developer experience.

Ensure that the document caters to people with special needs. The audience can have certain health conditions that might make it difficult for them to access the document. For instance, color blindness, dyslexia, visual impairment, and so on. Technical documentation should be made available for everyone regardless of their health condition. You can ensure this by adhering to something as basic as a checklist. Here is a series of posts from ClickHelp to help you build your inclusiveness checklist.

Be Comprehensive

If you are mentioning a particular concept, or a technique, make sure you cover just enough so that your readers are not alienated from it. Nothing can prove more dangerous than building assumptions about your readers. Having such assumptions and adding exclusionary statements to your document unintentionally conveys the message that your document is meant only for a certain level of developers.