In MadCap Flare 2017 r3, we introduced a new feature that lets you evaluate your Flare project content for readability, average sentence length, and more.
To run a text analysis, open your content file (e.g., topic, snippet). Select the Tools ribbon. In the Proofing section select Text Analysis. The Text Analysis window pane opens.
When you use the Text Analysis tool, you can run reports that analyze your content files using a number of options:
After you click “Analyze”, you’ve given results that show the reading ease score, grade level score, and more. But what exactly do these numbers mean?
Understanding the Score
Scores are based on “The Flesch Reading Ease” and “Flesch-Kincaid Grade Level” tests. The “Flesch Reading Ease” generates a score between 1 and 100 that roughly correlates to how easy or difficult it is to read the text. The higher the score, the easier it is to read the content. And if the score is low, the harder it is to read.
To make sense of the “Flesch Reading Ease” score, we’ve made it easy in Flare with colored bars; a green bar indicates a good score, yellow indicates an average score, and red indicates a poor score.
The “Flesch-Kincaid Grade Level” test is another readability metric based on the grade levels in the United States educational system. The score indicates the reading level; for example, if your content is rated as a 6, then it correlates to a sixth grade reading level.
When it comes to public-facing documents, the best practice is to aim for an 8th grade reading level. Long story short – you want to aim for a high reading ease score and a low grade level score.
For more information on how the scores are calculated, click here: https://readable.io/content/the-flesch-reading-ease-and-flesch-kincaid-grade-level/
Four Tips to Improving Readability
Running the Text Analysis tool can give you an idea of how easy or difficult it is to read your content. If your content is rated at a higher reading level or difficulty, there are several measures that you can take to improve readability:
1. Reduce Average Sentence Length
When analyzing content, the Text Analysis tool gives you a result on the average number of words in a sentence. A common best practice is to aim for 20 to 25 words in a sentence, but this rule varies depending on the type of content.
One guideline is to focus on the amount of information conveyed in a sentence. An appropriate length is if the reader is able to remember how a sentence begins and ends. Use bullet points to break up sentences crammed with information, or separate into shorter sentences.
2. Minimize Punctuation Density in a Sentence
If your results are showing a high punctuation density per sentence, it may be a sign that sentences are too long or convoluted. The following may be a factor in the high usage of punctuations:
- Comma Splices: Break up sentences where two independent clauses are separated by a comma.
- Quotation Marks: Instead of using quotation marks to convey emphasis, consider italicizing, bolding, or underlining the word instead.
To learn more about common punctuation issues, click here.
3. Cut Down on Paragraph Size
Long paragraphs with few breaks can quickly tire out a reader. This is especially so for online content, where attention spans are short and users are quickly looking for an answer. Aim to end a paragraph after a couple of sentences.
4. Watch Out for Unique Words
Another result in the Text Analysis tool shows the total number of unique words used in the content. If the number of unique words seems low compared to the word count, then it may indicate that there are repeated words throughout the content.
Look for whether sentences start with the same word, such as “I” or “we”. Or maybe there’s a particular word that’s repeated throughout the content. In short, this metric lets you know when there’s an opportunity to add more variety throughout your text.
There are numerous other factors that enhance the quality of copy, including structure, design, and more. But for users looking for a starting point, the new feature in Flare provides an opportunity to understand the overall readability of your content.
Do you have any tips on how to improve readability in documentation? Add your comments below!