3. Readability
The concepts of readability and comprehensibility imply that the act of reading beyond the physical act of seeing and deciphering characters and chunks of text is vastly more complex.
As the next step beyond this ‘raw’ level of input, we need to assume a process of tokenizing, akin to what a compiler does with the source code of a given program.
This process of tokenizing is what readability is concerned with. Thus, our writing will need to meet a number of requirements to successfully pass this stage:
1. The sentences must be well formed syntactically
2. The sentences must not exceed a certain length
3. The sentences should not be below a minimum length
4. Recursion must be kept to a minimum
5. The choice of words should vary
If a technical text is unreadable in the reader’s eye, he will quite probably assume that the product described in this text also is of inferior quality. Code is a language, just as the language of the documentation is. Not writing well in documentation implies faults in coding style.
Therefore, readability is an absolute requirement for documentation of successful products.
3.1 Well formed Sentences
By well formed sentences, we do not merely mean that the sentences should conform to grammatical rules of the English language, but also that they are clearly built. We will now look at some negatives and discuss solutions:
This sentence no verb
Glaring grammatical errors such as omitting a vital component of the sentence — in this case the verb — should be avoided at all cost. Read out loud, whenever in doubt. Usually, these mistakes occur in longer, more convoluted sentences. Check these twice when they cannot be rewritten in split-up form.
This sentence does a verb have
Never, ever try to transpose a grammatical construct of your mother tongue into a literal English equivalent — even more so in cases of colloquialisms, as above! If you are able to translate a sentence word by word back into your mother tongue, you most probably made a severe mistake or two in writing it. Read texts by native speakers of English. Rewrite your own text next, and then reread it.
In this case, we see that there is, as such, a larger than necessary number of commas.
Punctuation should be kept to a minimum. It is not necessary to put a comma wherever it looks right. They often are not. Especially clauses of the ‘so that’ type can do perfectly well without commas. This rule of course also holds for all other punctuation. And never, ever, try to transport punctuation rules from your native tongue to the English you are writing.
Of course, many more cases of sentences not well formed might be constructed, but quite probably you will find enough of these when looking through various pieces of writing. And not only will you find these in non-native writers of English. Therefore, again — read what others wrote!
Of course, most of the further examples of section 3 also are malformed in our wider sense.
3.2 Overlong Sentences
Often we encounter sentences which run on too long. Understanding such sentences is extremely difficult, as short term memory has a very limited capacity. Similar to the rule that telephone numbers may not have more than 5 digits plus/minus two; sentences should not exceed a certain length.
It is given as a rule, which however is not the only such rule you may encounter, that sentences should not exceed a desirable length of ten to fifteen words, never should fall below seven words or extend beyond the ultimate limit of tolerable length reached at twenty words, even though longer sentences may be found in high literature, where even punctuation as it is used in this example to facilitate reading is oft omitted in novel experimental ways.
This of course is an example that runs somewhat longer than what you would expect to find in your own writing. But read your own texts again and you will quite possibly find one or two of these abominations, describing say, a complex chain of events and their handling. A complex train of thought can only benefit from being broken down into sentences of convenient length. Temptation to ramble on in one long sentence may be great. Resist. Your logic will benefit. Also cut out anything not necessary to the immediate cause at hand. To quote Strunck and White’s third rule:
Omit needless words.
3.3 Short Sentences
Short sentences are easily read, but tend to look breathless and overly excited.
Sentences may be short. Then they are easy to read. And understand, too. But they look cheap. And breathless. As well as leaving the reader restless.
Not much needs to be said here, as these above sentences illustrate the point to be made. If a thing is worth saying, it is worth saying it well, not chopping language to pieces. Human language is not a RISC language.
In general, try to vary the length of sentences in the limits given in the negative of subsection 3.2 above. Interesting writing depends on well dosed variations of length and choice of words — for examples of the latter, see below.
3.4 Recursion
Sentences often turn into a quasi-circular case of recursion while reading them when the references made in the sentence to the respective objects and subjects are left unclear by using the same pronoun to describe these subjects and objects.
It is not easy to understand it when it is unclear what is referenced by ‘it’ – it by now should be clear what it is supposed to mean, isn’t it?
In such a case, replace one — preferably the first — instance of each subject/object referenced by ‘it’ with its actual name. This will make reading much easier. Recursion of this type often also is an indication of laziness on the writer’s part, as it hints at an unwillingness to formulate a thought properly. This however is only a short term saving of effort, as readers probably will contact the author asking for clarification and thus causing more unproductive work on the writer’s part than necessary.
Another form of recursion will take place in the reader’s mind when he is confronted with convoluted sentences containing insertions, ellipses and other rhetoric figures. All of these will need some place on his ‘stack’ — and a reader’s stack is shallow. ‘Pushing’ and ‘popping’ more than three stack levels usually ends in disaster … for the message of your sentence!
The reader, that is, the intended recipient of our text, a hopefully clearly written and logically structured document, will, if he is able to fully understand our prose, without difficulty come to a safe assumption of what any given sentence, such as this a one, conveys, to him, the reader, by the way of meaning.
The above sentence is grammatically correct, but will most probably provoke a ‘stack overflow’ in our average reader. Such convoluted1 writing should be avoided wherever possible. Just as recursive code, text may be ‘flattened out’. Take a monster such as the one above apart. Shorter sentences make easier reading. If this is not possible, try to keep related parts of the sentences as close to each other as possible.
3.5 Choice of Words
Using the same words all over to describe the same things again and again is not pleasant even more so when we can use different words to replace those same words we are using again and again to describe the same thing in the same words.
For any given word, at least one synonym will be available. Do not hesitate to use a thesaurus. Also, do not use the exact same phrasing again and again and again, unless it is intended to convey some artistic intention — this however is almost never the case in technical writing. And:
Never use the same opening words in two or more subsequent sentences. Repetitive writing is the enemy of all reader's interest.
No comments:
Post a Comment