About the speaker:
Carolyn Stransky is a journalist, software engineer, conference speaker and technical writer based in Berlin. This is how she describes herself on her website:
Majority of the week, I'm a frontend engineer focused on accessibility, design, and documentation. Beyond that, I'm a freelance journalist and editor. I'm currently the Acting Editor of Future of Sex with other recent bylines in Autostraddle, Silicon Allee, Curve Magazine, and elsewhere. Outside of work, I still try to keep a regular skincare routine and find time to binge Terrace House.

About technical documentation

Let’s start off with a question: Why do we even write documentation in the first place? Is it because someone told us to do it like our manager or the acceptance criteria in our ticket. Or is it because we actually want to help the people using our product and accomplish their goals?

Writing documentation tends to be an afterthought. Something we just need to get done when finishing a product. So, what if we gave it the same care and consideration as we do to the features we ship? Those questions lay the foundation to what is called: Use case driven documentation, which derives from the concept of goal driven documentation. Both were made popular by Tyner Blain in 2006. The key message is to make the goals of your user the focus point of your documentation instead of just describing interface elements from left to right. To show why this approach is so important Tyner uses the example of a power drill. If we were to document one in the same way most do with software, we would end up with something like this:

How to adjust the speed.

How to change the direction.

How to change the drill bit.

With this you would know how to operate the drill but not how to actually accomplish anything with it. These are examples of reference docs. They are information oriented and describe the machinery. But if we change our perspective and focus on what it takes to do the job instead of just using the tool it could look like this:

How to drill a hole in a flat surface.

How to select the right screw.

How to stir paint with your drill.

Suddenly the documentation is helping us in achieving our goals. To understand why this approach is successful we need to think about the first question: Why do we write documentation? And perhaps more important we should be asking: Who do we write documentation for? The answer is surprisingly straightforward: for Humans.
With the development of AI and sophisticated bots this answer could change soon, but at least for now most documentation is written with the intention that humans will read it as they need that guidance documentation is meant to provide. That's why the same principles from the example with the drill can be applied to our products as well.

Let’s look at a high-level outline of this idea. When developing a use-case the workflow could look something like this: Goals -> Use Case -> Functional Requirement -> Design -> Implementation
Now most documentation starts at the implementation phase so after the features are ready. But a use-case driven approach aims to start at - you guessed it - the Use Case. The beauty of this is you can design your documentation simultaneously with the features you are developing. When using a structured approach like this we have an established framework for defining the problems our software will solve. We articulate exactly how to work out those problems because the use cases define what we need to document.
But - unfortunately - even with the best intentions it doesn’t usually happen this way. 

“Nobody actually wants to read technical documentation” - This statement is accepted as the truth by many writers and developers alike. And when considering that most people take a look at the documentation when they are frustrated and don’t know further one can assume that it is truly an unwritten law.
But in reality people don’t mind reading and may even be thankful for the documentation as long as one key element is given: it needs to be actually helpful.
So how to achieve this? While we don’t have the ultimate guide on how to write helpful documentation, there are small tangible actions we can take to improve it.

The words we choose

As documentation becomes more advanced, particularly through AI and helper bots, the words that we use for writing will play a large role in how these tools learn and the subsequent materials that they create. We want those to be as neutral and inclusive as possible. 

One blocker to this goal is insensitive language. This one can be tricky because across nationalities and personalities insensitive wording can mean a lot of different things. In the case of a documentation it includes profanity or anything else that might break a code of conduct. 

For Example: “If the programmer wishes to uphold the invariant, he must satisfy the function’s preconditions.”

While some people think that gendered language is a relatively tame example, it can have negative effects on the members of the community and their own sense of belonging within the product. 

In software development we also have these problematic and outdated (mostly racist) terms that we are still using, even though it’s common sense in 2022 that they are offensive. Terms like Master/Slave or Whitelist/Blacklist should be avoided. Instead use Primary/Replica and Denylist/Allowlist for example. Not only are they not racist, they actually better describe their purpose via their semantics. 

Another example for not-thought-through wording is saying “symply” or “easy” in a documentation. When searching the word “simply” on GitHub you get over 92 million references to it. That’s an issue because if people are stuck on a problem do they really want to read something that describes it as simple?
What we can do here is banning isolating words like “easy”, “simple”, “obviously” etc from our docs. This is already a common practice for many technical writers and we can use this to be more mindful of the words we are choosing. When looking for alternatives try to be more specific. If your product is easy because it's quick to set up or doesn’t require much custom configuration then say so. Or be comparative: “something is smaller than something else or requires fewer steps to create”. Of course you can also be absolute: “it requires five lines of code to integrate this with your project”. 

Also don’t try to be funny and avoid jokes in your documentation. Humor is extremely difficult to localize and it may have legal ramifications depending on your project and more likely than not it will annoy your readers because typically they are trying to accomplish a task and then leave the documentation. 

The next point is one of the most common mistakes when it comes to bad documentation. Often they have long, verbose chunks of text filled with bloated language. To be more specific, that means overly complicated prose that is difficult to understand. So, choose your plain and intentional language as it’s crucial for more inclusive documentation. 

Code in documentation is almost as prevalent as words are so we should give it just as much care as the text that we write.
First, code snippets should never be screenshots. This is for accessibility reasons, because without alt text the code is unreadable to those using assistive technology like a text to speech program. But not only because of that it’s much more in your favor to write it out. That way people can copy and paste things to try them out on their own or even interact with the code directly if there is some sort of playground embedded into the doc.

To conclude, the aim of a documentation is not only to be accurate and consistent but also honest, helpful and human. Honest by communicating the pros and cons of a solution to build trust. Helpful - we want our users to succeed as theirs is ultimately our success. And human - we want to feel familiar and approachable. 

‍

Thank you for reading this article. If you are interested in hearing Carolyn Stransky herself you can do so by following this link and joining our platform.