‘Reading and comprehension skills’ is a term usually associated with schooling. We often hear these words pronounced by a school teacher and applied to students. We are used to thinking these skills are relevant only at the beginner stages of education. However, ‘reading and comprehension’ is a skill we use daily, actually, every time we come across a written text.
The higher the skills, the better the readers’ understanding of the message. But when a text concerns technical matters, the comprehension skill often fails, as many people, however well-educated they might be, have problems understanding the technical ‘gobbledegook.’ They will surely read the text, and their reading skill will be all right, but their comprehension will lag.
This is why technical documentation often has to be transformed (reviewed, edited, and sometimes totally written over) to make comprehension easy for an average user. Text readability indices will help you identify the documents that need to be ‘translated’ from technical jargon to ordinary language.
Why Is Your Documentation So Hard to Read?
Your product may include all the necessary help docs covering all bottlenecks and offering very detailed ways of troubleshooting. Still, users would prefer to contact your customer service instead of reading the FAQ section.
There may be different reasons why your technical documentation is so unpopular among readers. The most obvious are the following:
- Technical jargon. For example, if you write “CanCycle” which is a shortened form of ‘canned cycle’ meaning ‘a ready-made program cycle or set of steps to follow’ (a coined jargon word in an operation manual for a CNC lathe machine), 99 out of 100 of your readers will have problems with understanding this. So, make sure jargon words are avoided. It doesn’t matter if they are popular in your company and understood by everyone in the industry. They may be like ‘mother’s milk’ to you and a real headache for your readers and customers who want to hear normal human language.
- Technical terms. Another thing that may discourage users is the large number of terms used in your technical documentation. Terms are usually split into commonly known and rare terms. By way of example, in the field of IT, a ‘file manager’ is a commonly known term, while such words as ‘bus’ or ‘TCP’ refer to the category of rare or just unknown words for some people. This is why it is important to avoid terms. If this is impossible, make sure they are properly explained.
- Long words. Of course, this is very different in different languages. For French, three-syllable words are all right, while in German, a single word can be a line long. In English, one- and two-syllable words make the core of the vocabulary. So, if you write technical documents in English, make sure three- and four-syllable words are not too many. They may hinder comprehension not only because of the length but also because they are mostly borrowed into English from other languages (mostly French and Latin). A foreign origin is often totally forgotten, but some words are still perceived as foreign and require additional effort from the reader, for example, consulting a dictionary. You just have to bear it in mind in the process of content creation.
- Complex sentences. This is another problem that may hinder communication with customers. Complex sentences (aka ‘long’ sentences) are often hard to understand because, when the reader finally reaches the end of the sentence, the beginning is usually forgotten. So, don’t try to pack all information in one sentence. You will make it lengthy and overloaded with messages. Follow the KISS formula – keep it short and simple.
Most readability indices will help you identify long words and sentences. This will help you change your documentation so that reading will go smoothly. Ultimately, it will help to improve the UX parameters of your technical content.
The Most Popular Readability Indexes
All readability indices can be split into three groups according to the three principles they are based on. These principles are the ways the text is analyzed.
Group 1. Most indices (Flesch-Kincaid Grade Level, Flesch Reading Ease, Gunning Fog, etc.) are based on the analysis of the length of words and sentences. The longer the words and sentences, the higher the text complexity is, and the more difficult the text is to read and comprehend.
The indices in this group provide their own assessment scales that help pin the text on the ‘readability map.’ Each analyzed text gets its own readability score that puts it on a specific readability level.
The levels are tied to the US education system. That is why you can see such levels as a pre-kindergarten, 1st-5th grade, and the following grades covering all years of study from elementary to high school.
The assessment scale is the only difference between these indices. In a way, each scale reflects a subjective view of its developer on the readability issue. That is why the index often bears the name of its author, like Flesch-Kincaid, Gunning Fog, Coleman-Liau, etc.
Group 2. The indices here are based on syllable count instead of word count, as in the group above. The brightest examples are the SMOG index and the Forcast Grade. The principle of syllable count is the same in both cases, but the methods are different.
The SMOG Index focuses on the count of words with three or more syllables. Such words are considered long for the English language, and, as was said above, such words are regarded as foreign and require higher reading-comprehension skills from users. The number of such words is analyzed in a sample text fragment containing at least 30 sentences.
The FORCAST Grade uses an opposite approach. It is focused on the count of one-syllable words, which are considered easy to understand. This thesis is very contestable, though, because if you look at a dictionary entry for any one-syllable word, you will find that these are polysemantic words (have lots of different meanings). This can hinder understanding dramatically. Still, the FORCAST Grade is widely used as a readability metric for analyzing sample text fragments containing 100-150 words.
Group 3. Group 3 can be called ‘Miscellaneous,’ as it contains metrics based on separate original methods that cannot be grouped with others. For example, the Time to Read metric is based on the time factor. It allows you to estimate the approximate time a user will take to read the text. The longer it takes, the more complex the text is for comprehension and the lower its readability.
Another example in the Miscellaneous group is the New Dale-Chall metric. The text analysis is based on a predefined set of "common" words and the ratio of "difficult" words and words per sentence. The more common words the text contains, the higher its readability.
No matter what metric you choose, it will improve your documentation greatly. With the help of readability metrics, you will have a chance to look at your documentation with the eyes of your users or potential customers. What’s more important, you will be able to transform your content so that its user experience parameters will be enhanced.
How Flesch-Kincaid Grade Level Works
The Flesch-Kincaid Grade Level is perhaps one of the most popular readability indices. It is focused on searching for long words and sentences. The principle is simple: the longer, the harder to understand.
Each analyzed text is assigned a value 0 to 18 (18 for the most difficult text). The value corresponds to a certain level. The level range looks the following way: basic (with readability score from 0 to 1 pts) – easy (1-5 pts) – average (5-11 pts) – skilled (11-18 pts).
Each level has a description. This is important, as it gives a characteristic not only to the text but to the reader as well. For example, if a person can read texts that are assigned 5-11 points, the reader is at the average level. Their skills are typical for most readers (80% of readers in the US).
This is also good for understanding if your technical content will be comprehensible for the majority of readers. If the analyzed document is within the 5-11 range, it is okay. But if it exceeds this limit, it will be understandable only for a very limited group of people whose level is ‘skilled.’ This is the level of academic writing (academic papers, articles, etc.).
At the same time, levels correspond to school grades. So, using the metric, you can classify your content and your readers according to their level of school knowledge. This is why the method is called Grade Level.
For more detailed information about the interrelation between text complexity, levels of knowledge (reading skills), and grade levels, read here.
Readability Metrics in ClickHelp
ClickHelp is an online platform for managing content that provides users with a whole arsenal of tools to produce effective technical documentation with minimum effort, time, and cost.
It is based on the principles of content reuse and single-sourcing. This means that new documentation can be derived from the previously created content. However, in the course of reviewing, editing, adding, or deleting, the content might lose its initial ‘drive.’ Texts can become overloaded with new information that has to be added each time your product is updated. This can have a negative impact on the SEO and UX parameters of your content.
To avoid this, ClickHelp offers a set of metrics that can be used to analyze content in terms of readability. The metrics available in ClickHelp cover all the indices mentioned above and even more.
In addition to the methods already described in the blog, ClickHelp offers Automated Readability Index focused on the count of letters per word and words per sentence (which is more accurate than the count of characters as in the Coleman-Liau index). Another addition is the Linsear Write formula based on the number of words with three or more syllables in a sample of text containing at least 100 words.
What’s more, ClickHelp offers the Average Grade metric, which is an arithmetic mean of all readability metrics available on the platform. The Average Grade metric will help you make your content ideal for average readers using the accumulated results of all the metrics mentioned above.
Conclusion
User experience is an important factor that can influence the popularity of your product on the market. UX includes not only the navigability of your product but also how easy or hard it is to find the necessary solution. To help readers find the right answers to their questions, tech writers and developers provide users with supporting technical documentation.
This content is another element that contributes to the user experience. Documentation greatly impacts the impression your product produces on the users. If it is full of technical terms, jargon, and complex sentences, the user experience will be low.
To avoid this, ClickHelp offers its users a set of readability metrics. They will help to enhance the overall quality of your content and bring your documentation to a whole new level.
Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices