Technical Writing Made Easier

[ Pobierz całość w formacie PDF ]
//-->Technical Notes, general SeriesTechnical Writing made easierrev. 1.1, March 2002byBernhard Spuida,bernhard@icsharpcode.netSenior Word Wrangler© Bernhard Spuida, 20021Table of Contents1. Introduction.......................................................................................................................22. Theory..............................................................................................................................23. Readability........................................................................................................................33.1 Well formed Sentences............................................................................................................33.2 Overlong Sentences................................................................................................................43.3 Short Sentences......................................................................................................................43.4 Recursion.................................................................................................................................43.5 Choice of Words......................................................................................................................54.1 Definition..................................................................................................................................64.2 Assumption/Theorem...............................................................................................................64.3 Explanation/Proof....................................................................................................................64.2 Conclusion...............................................................................................................................65.1 Title..........................................................................................................................................85.2 Big Words................................................................................................................................85.3 It's............................................................................................................................................95.4 An 'a'........................................................................................................................................95.5 Do not use 'don't'.....................................................................................................................95.6 Can, could, etc.........................................................................................................................95.7 Nativisms...............................................................................................................................105.8 Ego Trip.................................................................................................................................105.9 When to use 'if'......................................................................................................................105.10 This Sentence does overdo it..............................................................................................105.11 Time is on our side..............................................................................................................115.12 Consistency.........................................................................................................................115.13 Editor's pet peeves..............................................................................................................114. Comprehensibility.............................................................................................................55. Matters of Style................................................................................................................86 Recommended Reading..................................................................................................157 Online Resources............................................................................................................155.13.1 Grammar and Logic.....................................................................................................................115.13.2 Spelling and Terminology............................................................................................................12© Bernhard Spuida, 200221. IntroductionTechnical writing requires clarity of expression and therefore simplicity of language. Technicalwriting is intent on expressing certain key concepts so that these may be understood as easily aspossibly by the intended readers — be they programmers or users. Writing in a clear, concisemanner makes not only understanding the text easier for the reader, it also makes your life as awriter of technical documentation easier — especially when you are not a native speaker of English.When talking about algorithms, or sequences of events in a program, absolute clarity of writing isnot only needed in the code discussed; but also in documenting this particular program for ourfellow programmers and users. We need to attain the same level of clarity of expression in bothcases, otherwise readers will to turn to other programs, which are more accessible on the level ofunderstanding and therefore easier to use or extend.In this short guide, we will cover some of the basic concepts that lead to good (technical) writing.You will certainly discover more such rules and concepts as you practice the writing skills gainedout of this set of notes. And also, read! Read a lot, and read varied writing, conscious of the wayslanguage is used in the texts you read. Have your own writing read and criticised by friends andfellow professionals. Pay attention to these criticisms.You will see that our colleagues, just like the computers we program, require a specific syntax to beadhered to if we want our instructions to be understood. And as in programs, human language textmay be straightforward or convoluted, leading as in programs to variations in performance. So herewe go.As this is intended to be a 'work in progress', additions will be made whenever necessary. I am alsoalways happy to receive suggestions and feedback.2. TheoryThe understanding of written text depends on three distinct components:•••LegibilityReadabilityComprehensibilityThe first of these components is of no concern to us, as it is a responsibility of the layouters andtypesetters putting our writing into its final form.The second of these we will deal with, as it is vital to having the reader actuallyreadour document,hopefully in full.And lastly, the third component is essential to ensure that our reader willunderstandthe purpose ofour writing.These two components will be discussed in separate sections, even though some of the issues raisedmay be pertinent to both.In addition, we will also look at issues of style — some of writing’s do’s and don’ts , as even theprose of technical writing does not have to be equivalent to a blunt axe when it might be aninstrument of precision.Should you, kind reader, have suggestions for improvement to these pages, please let me know:bernhard@icsharpcode.net© Bernhard Spuida, 200233. ReadabilityThe concepts of readability and comprehensibility imply that the act of reading beyond the physicalact 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 towhat 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 tomeet a number of requirements to successfully pass this stage:1.2.3.4.5.The sentences must be well formed syntacticallyThe sentences must not exceed a certain lengthThe sentences should not be below a minimum lengthRecursion must be kept to a minimumThe choice of words should varyIf a technical text is unreadable in the reader’s eye, he will quite probably assume that the productdescribed in this text also is of inferior quality. Code is a language, just as the language of thedocumentation 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 SentencesBy well formed sentences, we do not merely mean that the sentences should conform togrammatical rules of the English language, but also that they are clearly built. We will now look atsome negatives and discuss solutions:This sentence no verbGlaring grammatical errors such as omitting a vital component of the sentence — in this case theverb — should be avoided at all cost. Read out loud, whenever in doubt. Usually, these mistakesoccur in longer, more convoluted sentences. Check these twice when they cannot be rewritten insplit-up form.This sentence does a verb haveNever, ever try to transpose a grammatical construct of your mother tongue into a literal Englishequivalent — even more so in cases of colloquialisms, as above! If you are able to translate asentence word by word back into your mother tongue, you most probably made a severe mistake ortwo in writing it. Read texts by native speakers of English. Rewrite your own text next, and thenreread 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 looksright. They often are not. Especially clauses of the ‘so that’ type can do perfectly well withoutcommas. This rule of course also holds for all other punctuation. And never, ever, try to transportpunctuation rules from your native tongue to the English you are writing.© Bernhard Spuida, 20024Of course, many more cases of sentences not well formed might be constructed, but quite probablyyou will find enough of these when looking through various pieces of writing. And not only willyou 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 SentencesOften we encounter sentences which run on too long. Understanding such sentences is extremelydifficult, as short term memory has a very limited capacity. Similar to the rule that telephonenumbers may not have more than 5 digits plus/minus two, sentences should not exceed a certainlength.It is given as a rule, which however is not the only such rule you may encounter, that sentencesshould not exceed a desirable length of ten to fifteen words, never should fall below seven words orextend beyond the ultimate limit of tolerable length reached at twenty words, even though longersentences may be found in high literature, where even punctuation as it is used in this example tofacilitate 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 yourown writing. But read your own texts again and you will quite possibly find one or two of theseabominations, describing say, a complex chain of events and their handling. A complex train ofthought can only benefit from being broken down into sentences of convenient length. Temptationto ramble on in one long sentence may be great. Resist. Your logic will benefit. Also cut outanything not necessary to the immediate cause at hand. To quote Strunck and White’s third rule:Omit needless words.3.3 Short SentencesShort 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. Andbreathless. 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 thingis worth saying, it is worth saying it well, not chopping language to pieces. Human language is nota RISC language.In general, try to vary the length of sentences in the limits given in the negative of subsection 3.2above. Interesting writing depends on well dosed variations of length and choice of words — forexamples of the latter, see below.3.4 RecursionSentences often turn into a quasi-circular case of recursion while reading them when the referencesmade in the sentence to the respective objects and subjects are left unclear by using the samepronoun 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 beclear what it is supposed to mean, isn’t it?© Bernhard Spuida, 20025 [ Pobierz całość w formacie PDF ]