Technical Notes, general Series Technical Writing made easier rev. 1.1, March 2002 by Bernhard Spuida,
[email protected] Senior Word Wrangler © Bernhard Spuida, 2002 1
Table of Contents 1. Introduction.......................................................................................................................2 2. Theory..............................................................................................................................2 3. Readability........................................................................................................................3 3.1 Well formed Sentences............................................................................................................3 3.2 Overlong Sentences................................................................................................................4 3.3 Short Sentences......................................................................................................................4 3.4 Recursion.................................................................................................................................4 3.5 Choice of Words......................................................................................................................5 4. Comprehensibility.............................................................................................................5 4.1 Definition..................................................................................................................................6 4.2 Assumption/Theorem...............................................................................................................6 4.3 Explanation/Proof....................................................................................................................6 4.2 Conclusion...............................................................................................................................6 5. Matters of Style................................................................................................................8 5.1 Title..........................................................................................................................................8 5.2 Big Words................................................................................................................................8 5.3 It's............................................................................................................................................9 5.4 An 'a'........................................................................................................................................9 5.5 Do not use 'don't'.....................................................................................................................9 5.6 Can, could, etc.........................................................................................................................9 5.7 Nativisms...............................................................................................................................10 5.8 Ego Trip.................................................................................................................................10 5.9 When to use 'if'......................................................................................................................10 5.10 This Sentence does overdo it..............................................................................................10 5.11 Time is on our side..............................................................................................................11 5.12 Consistency.........................................................................................................................11 5.13 Editor's pet peeves..............................................................................................................11 5.13.1 Grammar and Logic.....................................................................................................................11 5.13.2 Spelling and Terminology............................................................................................................12 6 Recommended Reading..................................................................................................15 7 Online Resources............................................................................................................15 © Bernhard Spuida, 2002 2
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 tokenising, akin to what a compiler does with the source code of a given program. This process of tokenising 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. © Bernhard Spuida, 2002 4
English