# Usability and Readability Considerations for Technical Documentation

This chapter discusses the usability topics that you need to consider to create effective technical documentation. This chapter also briefly discusses readability tests for documentation.

## Usability Objectives

The usability objectives for effective technical documentation are as follows:

- Maximize speed of access to key information.

- Present accurate and complete information.

- Present specific information about specific topics.

- Make the most effective use of the delivery method, for example, online Help.

- Make the documentation the resource of choice for regular access, rather than, for example, asking colleagues how to perform actions.

## Things You Are Not Trying to Do

You also need to make sure that you do not inadvertently achieve the wrong objectives. For example:

- Do not try to resolve inadequate interface design in the documentation.

- Do not try to fix functionality bugs in the documentation.

- Do not distract from the task the user wants to perform.

## Strategies for Usability

Strategies that maximize usability must do the following:

- Reduce the burden on the short-term memory of the reader. Research shows that the average person can retain 7 ± 2 chunks of information in short-term memory. This does not necessarily mean that you must limit sentence lengths to seven words. You can group words together in familiar patterns to form single chunks of information. However, research also shows that a sentence length of more than 25 words overwhelms short-term memory.

- Build understanding and recognition of terms and structures into long-term memory. Research shows that consistent usage is the best way to achieve this goal. The more information that the reader stores in long-term memory, the lower the burden on the short-term memory.

- Provide clear navigation techniques.

You can employ the following strategies to maximize the usability and readability of your documentation.

### Eliminate Superfluous Information

Superfluous information gives rise to the following usability issues:

- Increases the amount of text that a reader has to understand before reaching the required information.

- Increases the amount of time and effort that a reader has to invest to access information.

- Takes up space in the short-term memory of the reader.

- Drains mental resources. The reader has a limited amount of mental resources. The more mental resources that reading the documentation takes up, the less mental resources are available for the reader to perform the required actions.

- Introduces the potential for confusion.

Examples of superfluous information are as follows:

- Unnecessary adjectives and adverbs

- Additional sentences that explain a concept in a slightly different way

- Information about other topics that is not relevant

- Personal opinions

- Speculation about future product functions

- Rhetorical questions

- Over-exposed legal information

- Over-exposed author information

### Create Consistent Structures

Create your documentation with repeated structures, using the same hierarchy of sections and the same type of information in the sections. By repeating the hierarchy of information structure throughout a documentation set, you train the user to look for certain types of information in certain places.

The structure of the documentation is like a street map. Obviously, a street map that is consistent across the whole of a city area is a better navigation tool than a street map that is inconsistent. The intrinsic, repeated structure of your document needs to feature all of the following characteristics:

- Orderly

- Logical

- Consistent

### Use Modular Information Blocks

Create modules that are short enough to reduce scrolling or page-turning to a minimum. Aim to eliminate scrolling or page turning completely for each individual module of information.

### Use Consistent Language

At school, teachers tell you to vary your writing so as to hold the interest of the reader. Technical documentation requires the opposite approach. Use the same vocabulary for the same purpose throughout your documentation. Furthermore, when a team of writers work together, they must write with a single voice.

You expect the terminology in a street map to be the same for the whole map. You do not expect particular areas of the map to have personalized terminology. Similarly, use of consistent language by a team of writers across the whole documentation set ensures that the reader is not confused by conflicting terminology.

Repeated use of consistent language builds long-term memory, and therefore reduces the demand on short-term memory. The reader can access the real information content of your text.

Other language points that you need to consider:

- Research shows that words with Latin and Greek roots are harder to understand than equivalent plain English words.

- Do not use non-English words, for example, Latin terms. Some readers might not understand the non-English word. Even readers that do understand the non-English word might need to pause and think about such a word.

- Short words are easier to process in short-term memory than long words.

- The active voice is easier to understand than the passive voice.

A major benefit from all writers in a documentation team using consistent language, is that localization is made easier. Localized versions of documentation add another dimension to documentation usability.

### Use Consistent Typographic Conventions

Where documentation structure is like a street map, typographic conventions are like street signs and road markings. Typographic conventions such as capitalization rules, punctuation, and emphasis tell readers what to expect. Consistent typographic conventions provide the inner structure of a documentation set. Inconsistent typographic conventions confuse and distract the reader.

Imagine the confusion if one area of a city uses different street signs and road markings than other areas. Or worse, imagine the chaos if one area of a city uses the same road markings as everywhere else, but to mean different things. No-one is in danger from inconsistent typographical conventions in a manual, however readers might not revisit the documentation if the conventions are confusing.

## Readability Tests

The main function of readability tests is to give you a quick assessment about the density of your writing. Readability tests cannot tell you how easily a reader can understand the information in the text.

You can perform readability tests manually by counting and doing a mathematical calculation, or by using word-processing software. There are several popular readability indexes, for example:

- Gunning Fog Index

- Flesch Reading Ease Scale

- Flesch-Kincaid Grade Index

### Gunning Fog Index

To calculate the Gunning Fog Index of a passage, do the following:

1. Count the number of words in the paragraph: W

2. Count the number of sentences in the paragraph: S

3. Count the number of words of three syllables or more: T

4. Apply the following formula: [W/S + T/(Wx100)] x 0.4

The Gunning Fog Index gives the number of years of education that your reader needs to understand the paragraph. Typically, in technical documentation, aim for a Gunning Fog Index between 10 and 15. The Gunning Fog Index formula implies that short sentences written in plain English achieve a better score than long sentences written in complicated language.

### Flesch Reading Ease Scale

Calculate the readability of a passage on the Flesch Reading Ease Scale in the following way:

1. Calculate the average sentence length: L

2. Calculate the average number of syllables per word: N

3. Calculate the score between 0 and 00%.

The higher the score, the easier the text is to understand. Aim to maximize the score. The Flesch Reading Ease Scale measures readability as follows:

100 | Very easy to read. | Average sentence length is 12 words or less. No words of more than two syllables.
65 | Plain English. | Average sentence length is 15 to 20 words. Average word has two syllables.
0 | Extremely difficult to read. | Average sentence length is 37 words. Average word has more than two syllables.

Click on the following link to find out more about the Flesch Readability Test. In this link, Rudolf Flesch, the developer of the test, provides some background information.

### Flesch-Kincaid Index

This index computes readability based on the average number of syllables per word and the average number of words per sentence. The score indicates the number of years of combined primary and secondary education that a reader needs to understand a text. For example, a score of 8.0 means that you can understand the text after eight years of combined primary and secondary education. Standard writing achieves around 7.0 to 8.0 on the Flesch-Kincaid Index.

Click on the following link to find out more about the Flesch-Kincaid Index and other readability tests. Although this web page deals with textbooks, you can also apply the concepts to technical documentation.