We have been mentioning readability on this blog quite a lot recently. No wonder, with modern trends like UX writing, this has become a real point of concern for may technical writing teams.

Luckily, readability is not that abstract, it can be actually broken down into pretty specific elements. Today, we are going to talk about five text metrics that need to be considered for creating better user manuals that can be understood easier.

Terms and Neologisms

Technical documentation is prone to contain too many terms, newly-coined words and abbreviations. This can hinder readers from full understanding of the text. Besides, this is one of the reasons why users don’t like technical documentation — interpreting all the unknown words and concepts takes too much time.

Terms and neologisms in user manuals can hardly be avoided, as technical documentation is based on very specific fields and subject matters. But, there are some ways to make it easier for all the unprepared readers.

All terms and new words should be explained in simple language. To help readers deal with difficult words in online documentation, you can:

• create links and cross-references inside user manuals
• add hidden parts of text with in-depth explanations
• create web help bubbles
• make up a glossary for reference

Word Length

It is quite clear that shorter words are easier to understand. If we also consider that on average 1 in 10 people has some degree of dyslexia that, among other things, can cause issues with reading, word length starts to matter even more.

There are two interconnected concepts here — length and frequency of use. Historically, they are kind of related. And, no wonder, we are sure that most of you would rather choose the word “start” than “embarkation” which are synonymous in certain contexts. So, in practice, this means that technical writers should control the length and frequency of the words they use — any restrictions are impossible here, of course, but, in general, to create nicer user manuals, one should start looking for more simple synonyms to awkward lengthy words.

Sentence Length

Here’s another metric related to length — sentence length. The rule of thumb is one sentence — one idea. However, some notions are hard to explain in one sentence, and that is alright, we’ll talk about paragraph division further, too.

For readability purposes, sentence length should be around 20 words, while some scientific papers and documents contain sentences with 60+ words. What is quite interesting, in literature, some writers manipulate sentence length consciously, to increase readers’ attention. Short sentences are intertwined with long ones to create a “rhythm”, where the shorter ones grab your attention and the longer ones help to hold it.

In technical writing, sentence length should help deliver a message clearly. So, our general advice is to try making sentences with around 20 words your default option. If you can squeeze your idea into even fewer words without losing its clarity — great, go with that.

Paragraph Division

Even Leonardo da Vinci, the greatest technical illustrator took advantage of paragraph division. Trully, paragraphs can help a reader get through the most complex help topic.

Basically, each paragraph should present and support one theme. This ensures that a reader can look through a text and get the main thoughts without reading the text thoroughly. Plus, getting information in chunks simply feels more comfortable and gives a breather to our brain to process it bit by bit.

So, don’t underestimate paragraphs and make sure that they constitute the backbone of your help topics.

Grammar Constructions

Sentences should be not only relatively short but also simple, as well. For example, abusing passive constructions can make your text feel much heavier. Active voice is more preferable.

It is difficult to say why people tend to use passive a lot, maybe because it adds some scientific feel and seriousness to writing… But, that’s a common misconception that technical documentation should be all sciency. On the contrary, technical communicators have been trying for a while now to make user manuals lighter and more appealing. And, getting rid of complicated grammar constructions is a sure way to do so.

Conclusion

The text is the core of technical writing. It can be viewed from many angles: grammar, style, logic, punctuation, readability, even its looks in terms of font and color. All components are important here, so, this post is meant to cover at least some small part of all the possible approaches.

We hope that takeaways from this article will prove helpful to you in your technical writing journey.

Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices