Technical Writing Made Easier - 17p

[ Pobierz całość w formacie PDF ]
Technical Notes, general Series
Technical Writing made easier
rev. 1.1, March 2002
by
Bernhard Spuida,
bernhard@icsharpcode.net
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
1. Introduction
Technical writing requires clarity of expression and therefore simplicity of language. Technical
writing is intent on expressing certain key concepts so that these may be understood as easily as
possibly by the intended readers — be they programmers or users. Writing in a clear, concise
manner makes not only understanding the text easier for the reader, it also makes your life as a
writer 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 is
not only needed in the code discussed; but also in documenting this particular program for our
fellow programmers and users. We need to attain the same level of clarity of expression in both
cases, otherwise readers will to turn to other programs, which are more accessible on the level of
understanding 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 gained
out of this set of notes. And also, read! Read a lot, and read varied writing, conscious of the ways
language is used in the texts you read. Have your own writing read and criticised by friends and
fellow professionals. Pay attention to these criticisms.
You will see that our colleagues, just like the computers we program, require a specific syntax to be
adhered to if we want our instructions to be understood. And as in programs, human language text
may be straightforward or convoluted, leading as in programs to variations in performance. So here
we go.
As this is intended to be a 'work in progress', additions will be made whenever necessary. I am also
always happy to receive suggestions and feedback.
2. Theory
The understanding of written text depends on three distinct components:
• Legibility
• Readability
• Comprehensibility
The first of these components is of no concern to us, as it is a responsibility of the layouters and
typesetters putting our writing into its final form.
The second of these we will deal with, as it is vital to having the reader actually
read
our document,
hopefully in full.
And lastly, the third component is essential to ensure that our reader will
understand
the purpose of
our writing.
These two components will be discussed in separate sections, even though some of the issues raised
may 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 the
prose of technical writing does not have to be equivalent to a blunt axe when it might be an
instrument of precision.
Should you, kind reader, have suggestions for improvement to these pages, please let me know:
bernhard@icsharpcode.net
© Bernhard Spuida, 2002
3
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
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?
© Bernhard Spuida, 2002
5
[ Pobierz całość w formacie PDF ]