“Keep it simple” is a well-known principle in documentation. A manual or description that is written to be simple has a far lower risk of causing errors. “Simple” refers not only to the structure of the text, but above all to the wording. How well a text reads can be measured using simple methods. Here’s a quick overview of how to do it and why you should measure readability.
Why should I measure readability in docs?
… to be able to recognise and revise documentation that is difficult to read. Good readability is often not the focus, especially for internal documentation. After all, subject matter experts are the target audience. Here are a few reasons why easy readability is still important:
- Misunderstandings, i.e. mistakes, occur less frequently.
- The text can be read more quickly. This means less time is lost.
- Readers can be more certain that they have understood everything correctly. This means that they trust the documentation more.
- Even non-native speakers can easily understand the text.
- New employees, unskilled temporary workers and trainees can all use the text.
- The text can still be understood correctly even when the reader is concentrating less (e.g., just before closing time, under time pressure, or while having a mild cold; or all of that at once).
- Other departments can use the documentation, even if they are not experts on the subject (e.g., the customer hotline).
So there are many reasons why we should measure readability – even if the primary audience for the docs are subject matter experts.
How can you measure readability?
Besides the content, 3 aspects determine how well a text can be understood:
- Layout: Images, highlights, and other visually prominent elements provide orientation for the eye, making it easier to consume the information.
- Structure: Short paragraphs and subheadings help the reader to grasp the topic.
- Formulation: Short sentences are easier than long ones. (Short) everyday words are easier than (long) technical terms.
The quality of the layout is difficult to determine. A few tips on what to look out for are given by Kris Schmidt in the article “The Art of Simple Information: Optimizing Knowledge Articles for Your Readers“.
But structure and formulation can be measured easily. In fact, this is common in marketing. The same measurement methods can be used for documentation, even if you may be aiming for different values.
To evaluate the structure, check the word count. MS Word and most other text editors can do this. So there is no need for complicated tools. A paragraph should have no more than 100 words. Try to have a new subheading after 300 words. It does not matter if the odd paragraph or section is a little longer. Good highlighting can make up for that. On average, however, these are the target values you should follow.
The level of complexity in the formulation of a text can be measured with the Flesch Reading Ease Score (FRE Score). There are many variants and adjuncts for this metric. The FRE score takes into account 3 properties:
- the language (German, English,…)
- the average number of syllables per word
- the average number of words per sentence
The score indicates how well a reader must be able to read in order to understand the text quickly. High values mean that the text is easier. To understand difficult texts, you need either more concentration or more prior knowledge.
In marketing, the target is an FRE score of 60-70. Only academics can fluently read texts with a score below 30. For documentation, the FRE score should therefore not be below 30. Values of 40-50 are usually easy to achieve and still sufficiently understandable for most users.
Measuring readability is easy. If you take care to write texts in an understandable way, you will create better, more useful docs. Tasks will be performed with greater speed and reliability. Moreover, the same documentation can be reused in many different areas because it can be understood even by people who are not experts in the subject matter. This saves time when creating and maintaining the documentation. Measuring readability is not just a gimmick, but a must for efficient knowledge management.