Introduction

As any company grows, it requires documentation to keep track of processes, architecture, cross-team functionality, and on and on and on.

To keep things organized and moving smoothly, we need to employ several kinds of writing, from administrative to conceptual to procedural. What is the difference?

• Administrative: reports, contact lists, white papers.
• Conceptual: the why. This may explain the company goals, what a certain process achieves, or why we use a certain tool to complete a certain task.
• Procedural: how to complete a certain project or task.

This last category, procedural, is also called technical writing, and is what I really want to talk about today. Specifically, its role in making information as accessible as possible to as many users as possible.

Our last post already touched on some of the improvements that we are making to our products to make them more accessible and inclusive. Today I want to reflect on what is going on with purely internal technical documentation.

What is technical writing and why do we need it?

Technical writing encompasses every kind of how-to documentation. For example:

• Onboarding
• Architecture
• Standard processes
• API documentation
• Incident response

Where necessary, it expands to include conceptual information that is integral to the inner workings of a project or task. Good technical documentation enables anyone, no matter how familiar with the subject, to understand a process. It should be brief (unlike this blog post), but extremely detail-oriented.

Creating documentation standards creates process standards, and thus, scalability. People can follow clearly-defined processes better than they can follow processes that are passed on by word of mouth or that are undefined. Additionally, people are much more likely to reference materials that are well organized, concise, clearly written, and easy to find.

Having good documentation also makes material accessible to everyone, not just the person who wrote it or the members of their team. (More on this later.) This helps new hires to the team, as well as individuals and teams that you may collaborate with. It also reduces the amount of time individuals spend explaining basic processes and requirements. It smooths the process of information-sharing, which reduces onboarding time, saves personnel hours, and helps us to de-silo our teams and organizations.

Additionally, having accurate accounts of what we have and have not done enables easy rollbacks.

Finally, having good documentation reduces the loss of legacy knowledge, and the risk of losing knowledge when the only person who knows how and why to do something leaves the company. (As our CTO likes to say, “because they won the lottery”.)

The Engineering team’s documentation

Enter the technical writer. (That is me!)

Technical Writing is a relatively new function to Numerator. That does not mean that nobody was creating any documentation before, it just means that prior to the employment of a technical writer, there was not a person whose specific (and only) job it was to create and maintain documentation for the Engineering organization.

What that also means is that there were no best practices or style guides in place.

When I started, what I found is pretty much exactly what you would expect for a company like Numerator that has been growing so explosively:

• What documentation there was, was scattered and out of date. There were a lot of materials that have not been updated since 2018, 2019, and 2020. (That is centuries for a company that has been changing as rapidly as Numerator.)
• Every team had a long list of outstanding documentation needs.
• How-tos were disjointed and very visual-centric.
• At no point did accessibility or inclusivity even come under consideration. (These are critical tools for good writing and clear communication, in both a professional setting and beyond.)

The following table provides examples of common accessibility and inclusivity issues that I have encountered in our technical documentation, along with sample solutions. Note that this list and my explanations are not exhaustive.

Why does this matter?

There are a couple of huge reasons that we need to do better. Consider the following information:

• Globally, about 15 percent of the population has some form of disability.
• Not all Numerator employees are native English speakers, but we only provide internal documentation in English. (Since this information can only be collected in voluntary surveys, it is difficult to provide a specific metric for this.)

At Numerator, our demographic and psychographic information helps our clients understand what changes they need to make to reach different groups of consumers. And just like that, we need to use the preceding demographic data points to shape our approach to documentation, both internally and externally. This helps create an environment where everyone can bring their whole selves to work, which is the Numerator way.

Remember, writing is not only about grammar and syntax. It is also about communication. For example, we can use writing to communicate an idea, a situation, or how to do something. Whatever the subject, the resource must be as accessible to one employee as it is to another.

Moreover, this must be done proactively. Even if we know that right now, a given team has no members who use a screen reader, we must recognize that that can change at any time. We do not want to be scrambling to update exclusionary language. As any engineer or content creator knows, being prepared is infinitely preferable to damage control.

What changes are we making?

This is an ongoing process. It is one that a technical writer can start, but that also requires the cooperation of everyone else involved. (This is particularly true in a situation like ours, where teams will be doing most of the routine maintenance on resources.)

To start with, we implement a style guide. What is a style guide?

A style guide outlines formatting and style standards. It is the same concept and function as a style guide for coding. As long as everyone follows it, a style guide ensures that content is consistent, accessible, and inclusive.

The exact conventions outlined in our style guide can change with the organization’s needs, but its tenets never do:

• Use global english: simple and precise English with no slang, idioms, colloquialisms, abbreviations, loan words, or contractions.
• Use accessible and inclusive language: provide every reader with the same opportunity to understand and experience what you have to say. For example, everything should be screen-reader friendly, use people first language, and use un-gendered references.
• Make it readable: readability is the quality of being easy to read. Keep sentences and paragraphs short, and if there is an easier way to say something, use it.
• Reduce cognitive load: cognitive load is the measurement of how much working memory is required to complete a task. Reduce the tax on your reader’s brain, for example break down long-form content, make it searchable, and do not use more than three orders of organization.

That does not seem difficult

So, summing up all of that, technical writing should be all of the following:

• Concise
• Consistent
• Readable
• Accessible
• Inclusive

You might think, hey, it is really easy to do. We have all had to write how-to topics in primary school, anyone can do that!

You already know what I am going to say.

Try it!

One popular exercise is the peanut butter and jelly test. Sit down and write instructions for how to make a peanut butter and jelly sandwich. When you are done, give your instructions to someone else and have them make a peanut butter and jelly sandwich following your instructions exactly as written.

Or you can just watch someone else do this online. You immediately notice that even adults struggle to accurately explain how to execute this everyday task. (I do really encourage you to try this, if for no other reason than entertainment value.)

What makes good technical writing difficult to do?

Well, if you watched or tried the peanut butter and jelly experiment, you know that one of the big challenges is that experience does not necessarily translate well. Good technical writing should be written for the perspective of someone who has never completed the project or task before. But a subject matter expert rarely has the ability to pull themselves out of their world of knowledge and approach the topic from that beginner’s perspective.

It is incredibly hard to do.

Subject matter experts have a tendency to overestimate what is and is not common knowledge. Something that might feel intuitive or inconsequential to someone already familiar with a process is easily overlooked. These could be small UI interactions, or something even more important.

Other difficulties include “technobabble”, colloquialisms, abbreviations, and acronyms. Not only do these drive up readability scores (which is not a good thing) and present potential issues for technology like screen readers, but they are also exclusionary to a wide range of people. Non-standard words like these may have extremely limited use region wise, or be unique to a particular company, job role, team, or even individual.

Add to that the fact that language is incredibly ambiguous. For example, refer to the following instruction:

“You can import new data through your configuration file or dynamically at run time. This may be a security risk.”

In the preceding example, it is unclear which of the following is the security risk:

• Importing new data.
• The fact that there are two different ways to import new data.

In a conceptual setting, there may be more context that clarifies the ambiguity. However, in technical writing, there usually is not. Wording has to be either very careful, or very detailed. (Sometimes in a way that may seem excessive. But I promise, it is not.)

Altogether, it can be a challenge to phrase an action in a way that cannot be misinterpreted.

Conclusion, further thoughts, and resources

For a year now, I have been rewriting our old documents, updating them as needed, and creating new materials, all following the style guide (and its tenets). There is still a lot of work to do.

But you know what?

I am increasingly encountering documents written by tech teams that are adopting these practices.

That is a huge win. Progress is the most important thing.

Inclusion also goes beyond the few examples mentioned here. Another aspect I did not mention is that we need to change our shared lexicon to use as much unbiased language as possible. One classic example of biased language is the branch naming convention “master and slave”. There are many alternatives, for example “production and development”. However, these changes meet with a lot of resistance because they require a lot of attentiveness and effort to make.

But to create a respectful and comfortable work environment, these are efforts that we need to make. To learn more about this, refer to Say This Not That. You can also download their guide for an easy reference tool.

No matter what your role is, to learn more about how to make your content more accessible, refer to the Web Accessibility Initiative home and the Accessibility Standards. For online content specifically, the standards are outlined in the Web Content Accessibility Guidelines.