Part 2Easy to understand


Whether technical information is easy to understand depends mainly on how it is presented at the level of small structures such as words and sentences. It can also involve larger structures such as examples and scenarios.

Chapter 5. Clarity

Focus on the meaning

Avoid ambiguity

Use words with a clear meaning

Avoid vague referents

Place modifiers appropriately

Avoid long strings of nouns

Write positively

Make the syntax of sentences clear

Keep elements short

Remove roundabout expressions and needless repetition

Choose direct words

Keep lists short

Write cohesively

Present similar information in a similar way

Use lists ...

Get Developing Quality Technical Information: A Handbook for Writers and Editors, Second Edition now with the O’Reilly learning platform.

O’Reilly members experience live online training, plus books, videos, and digital content from nearly 200 publishers.