Usability in Technical Documentation

Kesi Parker
3 min readMay 18, 2018

Usability is a measure of efficiency and satisfaction with using documentation. And the main goal of technical writers is to create technical documentation that will help users to interact with the product effectively. Unfortunately, many tech writers forget that the most important focus of tech documentation is the user. So this article will help you to create valuable documentation for them.

Create For Usability

The most important thing in technical writing is writing itself. You should keep in mind that you’re writing for users that interact with the product for the first time. Of course, you’re familiar with the interface but users aren’t. This is, probably, the most difficult thing for tech writers — abstract away from their product knowledge. Effective writing is an essential but not the only aspect of usable technical documentation.

Here are some tips for creating a usable document:

Language

Over the past decades, the tone of technical documentation shifted. We used cold tone, a user was something abstract. But documentation has become user-centered and more friendly, and now we use “you”. That’s why write your ideas in a clear and obvious way like you’re explaining it to your friends. Avoid the passive voice, complicated sentences and mistakes.

Formatting

Who did say that documentation should be boring? For example, color improves readability because it makes a text easier to understand by drawing attention to key points. Color attracts attention of the reader and helps to find information faster. So add some colors to your documentation.

Headlines are also an important aspect. As I said the main goal of technical writing is to explain difficult things in a clear manner. In order to make a large text easier-to-interpret technical writers usually divide information into small blocks and label them with headlines. Headings should be obvious and convey the message of the section.

Visual Content

“In the beginning, pictures ruled as a way to communicate ideas. They still do.”

-Guy Kawasaki

Some people may believe that tech writers only write something. But it’s not true. Technical writers also create visual content such as screenshots, graphs, gifs and so on. It helps to make technical documentation really interesting. For example, I use FastStone Capture for making screenshots and LICEcap for creating gifs. Your documentation shouldn’t consist of lots of text in small print.

As for me, I use ClickHelp. I examined their documentation before working with the program because I was a beginner in techwriting. It contains screenshots and gifs so I could interact with the product easily.

The screenshot of ClickHelp topic

Video Content

Speaking of visual content I want to give special consideration to video content. Nowadays the majority of people prefers watching videos to reading. And there is a strong reason — you can get more information in a short period of time. For example, I will learn much more about CSS styles from this 4 minute video than reading thematic topics.

Of course, at first, it’ll be difficult to create videos. But that’s worth the effort.

“I routinely receive feedback from users saying they “enjoyed the videos.” Almost no one says they “enjoyed the manual.”

-Tom Johnson

Feedback

As I’ve said above, imagine that you write a manual for your friends. So you can use your friends practically! Ask them to test a product with your manual and overwatch them. They reread paragraphs? Skip some steps? Well, your manual isn’t helpful as you thought. After this experiment ask them what is difficult for understanding? Why did they skip some steps? Maybe, they will tell you how to describe your ideas better.

I think these aspects are essential in creating usable technical documentation. Follow them and you’ll succeed in this sphere.

What are your best practices that help you to create usable technical documentation?

--

--

Kesi Parker

Job position: Freelance Technical Writer. Read my FAQ to learn more about me!