Have you ever picked up a user’s manual, a reference manual, or even a tutorial and found yourself more confused after reading it than you were before you started? Do you find that the “help” key on some software packages is helpful only after you have mastered the package?
Far too often, the appeal of innovative products is diminished because their documentation is too technical, wordy, or incomplete. If the word gets around that learning how to use your product is as easy as drinking water through a fire hose, your product, and possibly your company, may have an unfortunately short lifetime. If you have a reputation for producing clear, understandable user’s guides, you may gain a significant advantage over your competitors. Clear documentation will also decrease the number of service calls for trivial problems thereby providing you with more time to concentrate on complex questions.
There are many different scales that compute an index to measure the readability of a document. Of these, the best known is Robert Gunning’s Fog Index. It calculates a document’s “grade level,” which corresponds to the estimated number of years of schooling required to read the text without difficulty.
To compute the Fog Index, add the average number of words in a sentence to the percentage of “hard” words and multiply by 0.4. “Hard” words are those with three or more syllables except proper names, compounds of simple words, and three-syllable words in which the last syllable is “ed” or “es.”
Here is a paragraph from a technical article from a well-known organization:
Tests were devised that showed the resulting expert system could make reasonable diagnoses of the process irregularities experienced by other wafers, provided that at least some feature of the test structure signature of each respective irregularity had been previously cataloged in the knowledge base.
This paragraph has one sentence, 44 words, and nine hard words. Gunning’s Fog Index is then 0.4(44+20.5) = 25.8. Obviously, this is not the easiest passage in the world to read. It can easily be revised to read at the 10 to 12 level by dividing it into shorter sentences. It is possible to creatively construct passages that are very difficult to read, yet have a low Fog Index. However, this usually takes more work than writing clear text.
To make your sentences straight-forward, use active voice instead of passive voice. Active voice is much easier to understand when reading instructional material. For example, “The user should then edit his or her file using the XYZ editor” can be revised to read “Edit your file using the XYZ editor.” The second sentence is shorter, easier to read, and tells the reader exactly what to do.
Clear documentation must also provide a context for the readers in order to explain why they are reading the text. Ask yourself these two questions while writing each statement or thought: “Why?” and “So what?” Do your readers know why a certain instruction must be performed? If not, your documentation is probably less effective than it should be. For example, “Edit your file using the XYZ editor [Why?] to make the necessary changes.”
Writing clear documentation is not easy. You can’t rely solely on the Fog Index to determine readability. Have a colleague or a professional writer review your text thoroughly for simplicity and accuracy. Nobody likes to read through fog. Make sure your readers don’t have to.
By the way, this article’s Fog Index, not counting the passage from the technical article, is 12.3.
