How to Test Documentation Usability
Documentation is part of your product, whether your product is hardware or software. The success of your product depends on the user experience. The user experience depends in part on the usability of the documentation.
It is possible to wait until publishing to see if your documentation solves your users’ problems. However, a much more practical and proactive approach is to test the documentation’s usability prior to publishing.
Testing documentation usability allows you to know beforehand the extent to which the documentation will help product users achieve their goals. Based on the results of usability testing, you can make appropriate changes to improve documentation usability.
If you’re interested in learning more via video then watch below. Otherwise, skip ahead.
What is Documentation Usability?
Documentation usability refers to how easy it is for users to use documentation to achieve a goal or purpose.
Even though technical documentation must be accurate, relevant, and up-to-date, the purpose of technical writing and documentation is not to create accurate, up-to-date, and relevant documentation.
The purpose of technical writing and documentation is help to users and readers achieve a goal through a quick and efficient transfer of information. Examples of user goals include learning how to solve a problem or understand a concept or idea.
In other words, the purpose of technical writing and documentation is usability.
Why Do You Need to Test Documentation Usability?
As you test your products before releasing them to the customer, you can also test documentation usability. The purpose of testing in both cases is the same: to find how your product or documentation will perform with actual users.
A product or documentation that is released without appropriate testing cannot only lead to product failure, but it can also lead to loss of revenue, reputation, customers, and even lawsuits. Documentation usability testing will not only lead to improvements to the documentation, it will also contribute to the success of your products, increased customer loyalty and brand value, and business growth.
A team that can include product designers, technical writers, marketers, software developers, and subject matter experts creates documentation. The documentation team has its own perspective, mindset, and point of view: what appeals to the documentation team might not appeal to actual users. Therefore, the main reason to test documentation usability is to ascertain whether the documentation will help actual users.
Documentation will help users if they can find what they are looking for, understand it, and use it to achieve their goals.
Your product documentation enables customers to solve problems on their own. Documentation with low usability will lead to increased customer support tickets, increasing your customer support costs. With usability testing, you can ensure that your documentation has high usability, which will help you to keep customer support costs down.
Customers prefer self-service because it takes less time to solve problems on their own. Customers’ self-esteem also gets a boost when they are able to solve problems by themselves. If customers can solve problems on their own, feel good about themselves, and avoid the time and effort involved in going through customer support, they will feel good about you i.e. your brand. Customers will develop loyalty for your brand, which will lead to long-term customer retention and increased sales.
What to Test in Technical Documentation?
Now let us take a look at the specifics that you can test for your documentation.
Content Structure
When users access your product documentation, they are not interested in reading it from start to finish. Rather, they are looking for specific information that will help them resolve an issue or understand a concept or idea.
When testing documentation for content structure, check whether the content is split into appropriate sections, how easy it is to navigate, and if it is searchable.
Split Content into Sections
To make it easy for users to find specific information, you can start by structuring documents so that related information is divided into chapters or sections. Rather than going through the whole document, users can skim the document and read only the section(s) that contains information of interest.
Make it Easy to Navigate
Once you have developed a logical document structure with sections that contain related information, the next step is to display the structure in a way that makes it easy for users to find the section that contains information of interest. In other words, you need to make the documentation easy to navigate.
For documentation in the traditional multi-chapter manual format, you can do this by putting a table of contents at the start of the document. Another way is to add an index that contains key terms that users can search for.
The following image shows the table of contents (TOC) for the user manual of an industrial AC drive. Users can skim the TOC and go to the section that contains relevant information.
For online documentation, you can facilitate navigation by adding a sitemap or interactive table of contents.
The following image shows the table of content for Spunk’s online documentation. Users can browse through the TOC and click on the section that contains relevant information.
Make it Searchable
The other thing you must do is make your documentation searchable. Users will search for specific keywords e.g. how to install, how to troubleshoot, firmware upgrade, how to integrate, etc. Making documentation searchable will help users find all sections that contain information of interest.
Readability
There is a lot that you can do to improve readability. For the purpose of this article, we will focus on the use of active voice, avoiding long sentences, using medium-length paragraphs, and appropriate vocabulary.
Use Active Voice
Most style guides such as the classic Elements of Style by Strunk and White and the APA Style Guide recommend the use of active voice.
For active voice, the subject of a sentence is followed by the verb and then the object of the verb. E.g., the programmer wrote the code.
For passive voice, the object of the verb is followed by the verb and then the subject. E.g., the code was written by the programmer.
Even though the use of passive voice is allowed, the use of active voice has the advantage of creating direct, clear, and concise sentences.
Avoid Long Sentences
It is an intuitive concept that long sentences are harder to understand, and short sentences are easier to read and understand.
Consider the following example from a Google technical writing course: “The late 1950s was a key era for programming languages because IBM introduced Fortran in 1957 and John McCarthy introduced Lisp the following year, which gave programmers both an iterative way of solving problems and a recursive way”.
According to the Hemingway app, a popular writing tool, the long sentence has “poor” readability and is suitable for readers with post-graduate level education.
Breaking the long sentence into shorter sentences yields the following result: “The late 1950s was a key era for programming languages. IBM introduced Fortran in 1957. John McCarthy invented Lisp the following year. Consequently, by the late 1950s, programmers could solve problems iteratively or recursively”.
According to the Hemingway app, breaking down the long sentence into multiple short sentences leads to “good” readability and the text is now suitable for readers with grade 9 level education.
Therefore, to improve readability, it is better to use short sentences, and focus each sentence on a single idea.
Avoid Too Long or Too Short Paragraphs
Long paragraphs are intimidating and form a dreaded “wall of text” that readers ignore. Readers welcome paragraphs containing three to five sentences. Readers will avoid paragraphs containing more than about seven sentences. Therefore, it is better to divide longer paragraphs into separate paragraphs.
It is also important to avoid paragraphs that are too short. It is not that one-line paragraphs impede readability; rather they point to a lack of organization. Therefore, seek ways to combine one-sentence paragraphs into cohesive multi-sentence paragraphs or into lists.
Vocabulary
The use of appropriate vocabulary is essential for successful communication. If your audience does not understand the words that you use, then your documentation will lose its utility.
The use of complex technical language is appropriate if your audience includes engineers and other users with college degrees.
However, most documentation is written for the layperson. That is why it is better to match the vocabulary to the audience and avoid the use of jargon and complex terminology.
Content Quality
Good structure and readability only help if the content has high quality. Common criteria of content quality for technical documentation include:
- Accuracy: Inaccurate content will create rather than solve problems. Therefore, technical writers and other team members involved in documentation creation must ensure content accuracy.
- Relevance: Content that is accurate but outdated does not help users. Therefore, content must be relevant for today and reflect current research, trends, and information.
- Completeness: The content must include all the information customers need or want about a topic.
- Amount of information: The documentation must have the right amount of information, as too much or too little information about a topic can drive users away.
Visual Appeal
Good content structure, readability, and quality might not be enough for documentation accessibility. Visual appeal, even though much more of a subjective criterion when compared to the other usability criteria, makes a significant difference in how users perceive documentation.
There is no point in denying reality: humans are drawn toward aesthetically pleasing objects and make split-second judgments about visual appeal.
To make sure that your users value and make use of all the hard work that you put in to create documentation, it is worth taking the time and effort to provide your documentation with a design that has high visual appeal.
Use of appropriate font, font size, color scheme, layout, images, screenshots, and navigation elements can all contribute to increasing the visual appeal of your technical documentation.
How to Test Documentation Usability?
You can use the following three methods to test documentation usability.
Paraphrase Testing
Paraphrase testing focuses on user understanding. If users can repeat documentation content in their own words, it is a clear indication that they understand your content. If however readers are not able to paraphrase your content, then your documentation team needs to work on improving the content with respect to reading comprehension.
Task-Based Testing
You can use task-based testing to determine how easy it is for users to find and understand information. This testing method is the most relevant for documentation with instructions such as user manuals, installation manuals, and troubleshooting manuals.
If the results of task-based testing show you that users take a long time to find information, then you need to work on improving navigation and search.
If users are able to find information but are not able to understand it, then your documentation team needs to work on improving content structure, readability, and content quality.
Plus-Minus Testing
Dutch researchers Menno de Jong and Peter Jan Schellens devised the plus–minus testing technique. This technique focuses on the documentation as a whole: users are asked to go over the whole documentation and make recommendations regarding content that you need to add and content that you need to remove.
You can consider the results of the plus-minus testing as valuable feedback that you can use to review and improve your complete documentation.
Conclusion
Documentation often has serious economic, legal, or medical consequences.
Documentation with high usability will improve the customer experience, which will contribute to the success of your products, and consequently your business. Usability testing helps you ascertain how well your document works for the customers who use it.
Documentation usability testing gives you authentic feedback: instead of assuming or having to guess, you will learn about what works and what does not. Based on the results of documentation usability testing, your documentation team can make objective decisions about what to keep and what to modify.
