How to Write Inclusive Documentation

Those of us interested in improving the developer experience know that you can’t change it by focusing on only one thing. Sculpting a pleasant experience for your interaction with an organization’s technology, tool, or framework requires making sure that multiple aspects are constructed well and working together. This makes the developer journey smoother and improves the developer experience in the process.

However, some aspects of the developer journey are often overlooked. Even more frequently, places where the experience could have been more refined create missed opportunities to enhance the overall process of learning how to use something new effectively.

One of the aspects of the developer experience that often gets overlooked is the language inside of technical documentation content. Making sure your content is inclusive and empathetic is just as important as ensuring its accuracy. The changing demographics and increasing complexity within the tech field make inclusion and empathy more important than ever for creating a great developer experience.

Changing Demographics in Tech

Google defines inclusiveness as “the practice or policy of including people who might otherwise be excluded or marginalized.” Many times when we think of the word, we think of it pertaining to commonly-discussed aspects: race, gender, sexual orientation, etc. While these are absolutely examples of some of the groups that need to be kept in mind when it comes to inclusion, another aspect, particularly in the developer world, is educational background.

Gone are the days when there was one curriculum that everyone completed to get started on the developer career path. Now, with the growing demand for this skill set, many people obtain their skill sets in a multitude of ways. Some still pursue formal degrees in the computer sciences, while others teach themselves. Still, others participate in coding boot camps. It all focuses on programming and development. However, without an overarching standard for all of these programs to adhere to, it can be near impossible to tell what skills and knowledge a developer has simply based on their chosen form of education or years of experience in their chosen field.

Increasing Complexity in Tech

The tech space is always increasing in size and complexity. Every day, there seems to be some new language, tool, or framework. This is far from surprising considering the ways in which technology has become inextricably integrated with our daily lives. Now, it is becoming increasingly expected for seemingly disparate things to integrate with one another seamlessly.

What does this imply for developers? It means constantly learning new concepts, using tutorials, and following numerous guides just to keep up with the ever-growing body of information. While it may be tempting to equate developer skill with a wide breadth of knowledge pertaining to new-and-upcoming technologies and solutions, this is not usually the case. Experience comes from understanding a wide range of concepts and the frequent practice of applying solutions to a diverse set of problems.

This is where inclusive documentation comes in. It is extremely important that your documentation speaks to developers from all educational backgrounds and facilitates learning from an empathetic perspective. This means ensuring that your documentation doesn’t contain condescending or exclusionary language. But what does that look like?

Eliminating Condescending Language

Condescending language can appear innocuous enough when developing documentation. We often see examples like “…just install XYZ,” “…simply add X into Y,” or “It’s easy.” What we often don’t think about is “easy for who?” By including these types of statements in your documentation, you’re revealing the assumptions you’re making about your audience and implicitly creating an image of who you “want” your users to be. If someone doesn’t find the instructions easy, simple, or basic, your casual descriptors can come across as condescending. You’re also unintentionally excluding people from your documentation who interpret that as an indicator that they are in some way not skilled enough or not smart enough to engage with your content or the technologies it describes.

This is a detriment to the overall developer experience of your content and your organization as a whole. The key to a great developer experience is making the developer journey as frictionless as possible. Encountering dismissive or assumptive language is a sure-fire way to introduce friction into the developer experience. It unnecessarily communicates to developers that your tech, tools, or products are only for a certain level of developers. More so, it lets them know that you assume that if they don’t find a certain task “simple” or “easy,” you consider them less skilled or more of a beginner, two assumptions that aren’t necessarily true. There’s not a problem with being a beginner, but that’s not a reason to imply that someone is or to imply that your content is somehow “more advanced” than most programmers.

Removing Exclusionary Wording

This is not to say that words like “simple” and “just” are the only way in which documentation can be non-inclusive. There’s also the kind of language that’s been baked into the tech sphere for a long time.

Keeping things gender-neutral is one way to prevent excluding your audience. Using the second-person (you, your, yours) is a great way to foster a sense of connection with your audience. It’s also an effective way to structure instructional information of any kind since the reader feels like they’re being addressed directly.

Terms like “master-slave” to describe technical relationships carry a fair bit of historical weight, a burden that can affect members of the ever-growing, ever-diversifying field of development more than others. Some alternatives include “primary-replica,” “hive-drone,” and “agency-operative.” With so many established organizations replacing such terminology with more neutral terms, it says something about your organization when you choose to keep using this potentially offensive terminology.

Writing with Empathy

With so much information to learn and keep up with, making sure that learning your content is as seamless as possible is becoming more important every day. You are constantly competing against tech that offers a better developer experience. But how do you determine whether you’re creating experiences that help rather than hinder your developer audience? You keep empathy in mind.

Creating a good developer experience happens on multiple different fronts, documentation included. In order to keep your developers in mind, you must make sure to write with empathy. Without walking in your developer audiences’ shoes, you cannot truly mold a pleasant experience for them. One of the key ways to show empathy for your developers is through your style of documentation.

When creating documentation for an external audience, it can become difficult to separate our knowledge of the subject from our writing. This is called “the curse of knowledge,” the inability to disregard your knowledge on a topic enough to consider how those without your knowledge would view the topic. You have to keep this in mind while writing documentation for your users.

Whenever possible, make sure you test your documentation with those outside of your department, at the very least. This doesn’t mean that the people should understand every term you wrote, but they should be able to follow the general logic of the steps. Putting your documentation through this test is a small way to reinforce the idea of empathizing with those brand new to your technology.

Using Tools to Help

There are a bunch of tools created by developers to keep your documentation inclusive. Integrating these tools into your content-creation process can make keeping your documentation inclusive less of a manual process. One of my preferred tools is alex.js. Alex can be used in a variety of text editors or from the command line.

Conclusion

Don’t make the mistake of thinking that your documentation isn’t part of your product. In some cases, your docs are the only way for your audience to interact with your technology before fully committing to it. Making sure that such an important part of the developer journey is as inclusive and empathetic as possible is a great first step to enhancing your developer experience.