abc
Technical Writing Guide
Guide to Technical Writing: (2) Writing
Good English
S.Q1000.90.3
Issue: 1.0
Status: Definitive
11th March 1998
Originator
Tracy Marshall
Approver
Quality Manager
Copies to:
New Joiners
Quality Web
abc
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
Contents
1 Introduction
4
2 Stop Before You Start
4
3 The Ideas
5
3.1 Ordering your ideas
3.2 Completeness in the flow of ideas
3.3 Maintaining perspective
5
6
9
4 The Words
10
5 Simplicity
13
5.1 At word level
5.2 At sentence level
5.3 At paragraph level
5.4 The fog index
5.5 An American example
6 Shortness
6.1 Stretched-out sentence openers
6.2 Repetition
6.3 Padding
7 Lists
7.1 Introduction
7.2 First an example
7.3 The mechanics of lists
7.4 Finally
8 Strength
8.1 Conviction
8.2 The passive voice
8.3 Instructions
8.4 Weak verbs
8.5 Redundant words
8.6 Variety, the spice of life
9 Clarity
9.1 Ambiguity
9.2 Presenting ideas in a logical sequence
9.3 Vague words
9.4 Too condensed?
10 Correctness: Grammar and Punctuation
10.1 Grammar
10.2 Some tips on grammar
13
14
15
16
16
17
17
17
17
19
19
19
20
22
23
23
24
25
26
27
27
27
27
28
28
29
29
29
29
Page 2 of 35
abc
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
10.3 Common grammatical howlers
10.4 Punctuation
30
32
Document Control and References
35
Changes history
Changes forecast
Document references
S.Q1000.90.3
Issue: 1.0
35
35
35
Page 3 of 35
abc
1
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
Introduction
This document is adapted from Praxis plc’s document N054.40.2, Guide to Technical
Writing: (2) Writing Good English, written by Paul Newman. It contains advice about
document planning and writing style and a useful reference on common grammatical
mistakes and punctuation rules. Writing style is individual and the advice presented
should be used by the reader to improve their own style. The correctness of grammar
and punctuation is rather more objective and the reader is strongly recommended to
use these sections as a reference.
This document covers the preparation of technical documents in general, not just the
preparation of Praxis Critical Systems standard documents. Refer to [1] for the
mandatory requirements and guidance on the layout and style of the Praxis Critical
Systems Standard Document.
This document will be reviewed from time to time by Tracy Marshall, the Praxis
Critical Systems Technical Author. Any suggestions for improvement should be
addressed to Tracy.
2
Stop Before You Start
You may think that “writing good English” is about words: choosing the correct
words, and stringing them together grammatically.
But the difference between a well-written document and a poor one lies, more often,
in a deeper problem: illogical thought.
Spelling mistakes can be jiggled electronically; poor grammar can be zapped locally.
These are easy problems to flush out. But if a document rambles incomprehensibly, if
its ideas come in a puzzling order, if its sections don’t hang together, its paragraphs
are in the wrong order, and its sentences are back-to-front, then no amount of
“English improvement” will cure its endemic confusion.
So often the “badness” of a badly-written document has to do with its thought patterns
rather than its “English”. Poor thinking may occur at the document level, at section
level, at paragraph level, at individual sentence level, or all of them. The problem is
the same: ideas don’t flow logically. They come in the wrong order, repeat
themselves, or are absent altogether.
Accordingly this issue of “Writing Good English” tackles the subject under two
headings:
•
Section 3 “The Ideas” deals with the topic of assembling thoughts.
•
Section 4 “The Words”, gives guidelines for writing in a brisk, easy-to-read
style, expanded in Sections 5 to 9. Section 10 points out some common
grammatical errors.
Page 4 of 35
abc
3
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
The Ideas
What appears to be a sloppy or meaningless use of words may well be a
completely correct use of words to express sloppy or meaningless ideas
– anonymous diplomat
This section hopes to get you thinking about your writing, before you start writing.
People who don’t much like writing may view this as an irritating interruption to a
tedious task. I would make two points:
•
I have the strong impression that when people get bogged down in writing a
document, the reason usually is that they haven’t thought through the things
they are trying to say. What appears to be a mental block over words and
sentences is really a lack of clarity in the flow of ideas. In my own experience,
when one’s ideas have been clearly rehearsed, writing them down comes . . .
like magic.
•
A well-written document is one whose ideas are easily extracted. This has
something to do with a happy use of the English language (the subject of
section 4 below); but it has even more to do with the state of clarity, or muddle,
in the writer’s mind.
Let’s consider this topic under the following headings:
3.1
1
Order, at document level, section level, sentence level
2
Completeness
3
Maintaining perspective
Ordering your ideas
Let’s invent Rachel, a fictitious user of a document.
The problem
Rachel cannot extract ideas properly because she is confused about the document’s
layout; and, when she starts to read, she rapidly becomes muddled at the detailed
level. She finds herself flicking backwards and forwards through it. She is not even
sure about its scope.
The cause
The muddle resides not in the mind of the user (Rachel has an extremely ordered
mind), but in the mind of the writer. Curiously, many readers will jump to the
conclusion that the fault lies in their own lack of knowledge or intellect.
This failure may have several causes:
1
In truth the writer does not properly understand the subject matter himself. He
hopes to disguise that fact by using wordy language which avoids clear testable
statements.
Page 5 of 35
abc
2
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
The writer has failed to think before writing. He hopes that the process of
writing will cause the thoughts to come. He will then shuffle them into some
sort of order and hope that he hasn’t omitted anything. In particular:
•
He has plunged into his writing without preparing a skeleton of the
document. The document does not have a logical and visible structure.
•
He has prepared a skeleton, but it did not contain enough detail. He has
started writing individual sections experimentally, without having clear
in his mind the exact scope of that section and the logical flow of ideas
within it. He finds himself changing his mind as he writes, restructuring
the section and moving material between sections.
•
He starts each sentence by typing the first idea that comes into his mind;
then stopping to work out what he needs to say about that idea. The rest
of the sentence is a desperate struggle to . . . complete the sentence. For
an example of this problem see section 9.2 (Clarity).
The Solution
It’s all about thinking ahead. Here are a few tips.
3.2
1
Select a good title for the document. Does it really mean anything? Does it
need further explanation?
2
Whatever the length of the document, plan its structure fully (see [2]). Before
you start writing make sure that you have a full set of headings and subheadings (with meaningful and helpful names), and a synopsis of what each
section and sub-section will be about. Make sure that this skeleton covers all
the topics, and does not include anything that should really be omitted.
3
Arrange the document’s sections in a logical order. Consider how you will
cross-reference the different parts. Will it be easy for Rachel to go straight to
the section she needs?
4
Use paragraphing to break the text. Base this on subject-matter, not on preconceived ideas about how long a paragraph should be.
5
Don’t start on a new sentence until you have a clear idea of what it will say;
then arrange it so that its ideas are in a logical order.
Completeness in the flow of ideas
The problem
Rachel cannot extract ideas properly because she can’t make sense of the document.
She is missing some vital information that the writer knows, but she doesn’t.
The cause
The writer has quite simply left things unsaid. This can arise in many ways:
1
The writer has failed to target the user of the document. Who is she? What
does she already know about this project, and about this subject in general?
Page 6 of 35
abc
2
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
The writer has failed to provide a front end to the document, which throws light
on subjects like these:
•
why did I bother to write this document?
•
what happened before I wrote it, that the user needs to know?
•
will the document have an effect on something that is going to happen
later?
•
the document is impressive, but how does it really improve the reader’s
world?
•
what should the reader do when she has read it?
3
The writer has helpfully divided his document into sections; but, apart from
cryptic one-word titles, he has omitted to provide any context for the
information in each section.
For example, he has a section called
“Requirements”, which provides no information about these “requirements”
except to list them. Whose requirements are they? How and when were they
identified? What is their current status? What activities will they provoke?
4
The writer (or his project) has invented some handy terminology. His
document is about “characteristics” and “options”. He knows what these are,
and so do the project members who reviewed the document. Regrettably
Rachel does not. She is doubly confused because they match words which she
already knows, and she jumps to the wrong interpretation.
5
The writer has provided pretty graphs, matrices, flow charts, RADs, and bar
charts. But he hasn’t explained what a tick in one of the matrix’s boxes
actually means, nor why some of them appear in brackets. Neither has he
explained what a symbol resembling a trombone means; nor what the shaded
boxes signify. The diagrams have no introductory text which explains their
relationship to the rest of the document: what problem is this diagram solving?
6
The writer has provided lists of things, some thoughtfully consigned to
appendices. But he hasn’t said what they are lists of. There is no introductory
text. What do these items have in common? Are they a complete set of their
type? Where in the document does the list, provided in this appendix, throw
light into what would otherwise be darkness?
The solution
The examples given above (they are only examples) clearly have a common element.
The writer has given insufficient attention to the thought processes of the document’s
user. What the document should really be doing is conducting its user through the
entire logical sequence of ideas which the reader needs to use the document.
Notice that this is true not just for a document which will be read sequentially from
start to finish. It is also true of reference documents, where the user will read only
small bits at a time. It is a question of what information the user needs. A dictionary
does not need to start by explaining the way its contents are listed, because the user
will know that. But it cannot just start at “A”. It needs to explain the abbreviations it
uses, the phonetic conventions used for conveying the sound of words, and any
Page 7 of 35
abc
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
criteria which it uses when deciding which words to list. Users of the dictionary may
need access to these ideas in order to wield the dictionary effectively.
The user cannot be expected to make mental leaps to embrace ideas known to the
writer but not expressed in the document. How then can the writer be sure to avoid
leaving these vacuums? This is a difficult skill. It is not obviously a “writing” skill,
yet it is arguably the greatest writing skill of all. It is about communicating, and
communicating is about understanding the mind of another person.
Having thrown up this philosophical point, here are a few tips.
1
Start by considering carefully what kind of person will use the document:
Rachel. If Rachel hasn’t entered your head, there isn’t much hope of writing
effectively. Why will Rachel want to use this document? When and how will
she use it? Consider how you would present the information to her face-to-face,
and what questions she would probably interrupt you with.
2
Work through the logical thought-processes the user of the document will
follow. What is her aim? What does she need to know first? What information
is she really looking for? How will she expect to extract it?
3
Try drawing up an unstructured list of all the ideas (in generic terms) which
will need to go in. Add to this list whenever you think of something. You can
structure this list later.
4
Use this preliminary work to produce a structure for the whole document,
listing all sections, and including a brief synopsis of each section. Consider
which ideas will be best presented graphically.
Here are some more specific ideas:
1
Keep clear in your mind the distinction between the following types of
preliminary information. Make sure you include the appropriate ones, and
don’t use the wrong title for your introductory sections.
•
Introduction: This is a hold-all for introductory information. Depending
on need, it will contain information about the background, context,
scope, and readership of the document; give an overview or summary;
and describe how to use the document.
Every document should have an introduction in one form or another, though not
necessarily bearing the bland title “Introduction” (if you do use this title,
make sure it doesn’t blur the distinction between the following concepts).
•
Background or Context: These give the reader information which
precedes the document, chronically or logically; in other words,
information which does not appear elsewhere in the document but which
explains the document’s existence.
•
Overview or Summary: These provide the user with a map of the
information which does appear in the document.
Page 8 of 35
abc
•
3.3
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
Management Summary: This is really a separate document addressed
to a different audience. It therefore has a different purpose, and may not
be a strict summary of the rest of the document.
2
In anything other than a short document, break it into individual sections with
meaningful titles. Start each with enough introductory information of its own,
so that the assumptions underlying that section are clear to the reader. Consider
providing an overview of the section.
3
Introduce lists properly so that readers can see what the list consists of, and
what its purpose is.
4
Make sure that graphically-presented information is truly comprehensible.
Having designed it, and slaved over its production, you will be well familiar
with its exact meaning. Do the symbols you have used need explanation? What
exactly is the list of things in the left-hand column? Some people can extract
information easily and intuitively when it is presented graphically. Some
cannot. Add textual support. Make clear where the graphic fits into the
document’s flow of ideas.
5
If it is handy to use terminology which the user of the document may not
understand, explain it. If the term appears in only one part of the document,
explain it locally. If it appears throughout, consider adding a glossary at the
beginning or end.
Maintaining perspective
This section really summarises the last two. It is easy when writing to focus so
closely on the detailed information that you lose sight of the overall structure and, just
as important, lose sight of the reader’s point of view. Generally this doesn’t happen
when talking to somebody, because you can tell by their reactions whether they are
still with you.
Good planning goes a long way to solving this “nose-to-the-grindstone” problem.
Indeed one of the hidden benefits of planning is that, once you have decided where
the information fits, you are free to concentrate fully on the difficult local detail.
Do stand back occasionally and make sure that you are still in touch with your reader.
Have a break and come back to it. Before you issue a document, even as a draft, put
yourself in the position of the reader and read it through afresh. Even better, get a
colleague to read it.
Page 9 of 35
abc
4
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
The Words
Some writers seem to think that if they can drag in plenty of long or
unfamiliar or technical or modish words, arranged in long and involved
sentences, their readers will regard them as clever fellows and be
stunned into acquiescence. Not so: most readers will be more likely to
think: “This man is a pompous ass. I’m not going to agree with him if I
can help it” – Sir Ernest Gowers [3]
What characterises a well-written document?
An impressive command of the English language
The writer is obviously very clever
A striking style
Correct grammar, spelling, punctuation
no
no
no
yes
Easy to follow
Seems to make the subject less weighty than you thought
Holds your interest
Seems to talk to you personally at your level
yes
yes
yes
yes
The purpose of speech is to get an idea as exactly as possible out of one mind into
another. So it is with writing. Many people think that “written English” is a special
kind of language which is:
•
•
•
formal and impersonal
full of long words and complex sentences
learned, weighty, impressive.
As a result, when they have to produce a written document they get tongue-tied, or
they take refuge in churning out a boggy morass of verbiage that sounds impressive
but communicates little.
This disease afflicts adults. Why? A ten-year old wrote the following description of a
cow. The ideas are immature, but the writing is excellent. It is vivid, memorable,
speaks directly to you, and would actually convey quite a lot to an intelligent adult
who had never seen a cow.
The cow is a mammal. It has six sides – right, left, an upper and below.
At the back it has a tail on which hangs a brush. With this it sends the
flies away so that they do not fall into the milk. The head is for the
purpose of growing horns and so that the mouth can be somewhere. The
horns are to butt with, and the mouth is to moo with. Under the cow
hangs the milk. It is arranged for milking. When people milk, the milk
comes and there is never an end to the supply. How the cow does it I
have not yet realised, but it makes more and more.
Adults cannot excuse themselves by saying that they have to say more complicated
things. There are plenty of examples of technical ideas being communicated in clear
language:
The major organs of a turbo-jet engine are: a compressor, a combustion
chamber assembly, a turbine, and an exhaust pipe ending in a jet nozzle.
Page 10 of 35
abc
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
Large quantities of air drawn in at a front intake pass through these
organs in that order. The flow through the engine is continuous. In the
combustion chambers the air compressed by the compressor is heated by
the steady combustion of fuel. The compressed and heated gases then
pass through the turbine thus providing the power to drive the
compressor to which the turbine is connected by a shaft. They then pass
along the exhaust duct and emerge from the jet nozzle as a high-velocity
propelling jet. – Sir Frank Whittle
Often ideas that seem complicated are really simple, but shrouded in complex
language. The following two passages say very similar, straightforward things; the
first has been made unnecessarily hard to understand, the second has not.
There is a need for flexible resource allocation procedures to allow
updating of investment decisions so that at any given point in time of the
planning design process an optimum investment decision can be made
rather than one which may have been valid at the inception of planning
but has become progressively non-optimal (in the same way that this
pompous sentence has become progressively non-optimal?).
There are several very good reasons why the farmer, busy as he is,
should keep proper records of his business. It is the only way in which
he can find out how much profit he has made, and how one year’s profit
compares with another. It helps him to manage his farm efficiently, and
shows him how the various operations compare in outlay and in receipts.
So how should we write?
1
Written English need not be pompous, grand, magnificent. Write in a brisk
style as if you were speaking. But bear in mind these differences:
•
You cannot wave your arms, or smirk, or inflect your voice. All your
meaning must be in your words. There is more room for ambiguity.
•
Because you have time to think clearly, you have the opportunity to
express yourself accurately, concisely, logically, and simply. Think
carefully about the person you are writing for.
•
In much (not all) written work you are expected to avoid colloquial
expressions, and the spoken abbreviations like isn’t and don’t.
2
“Good style” is not something fancy, clever, or poetic. It means simply the
pleasing effect of language used efficiently for the job in hand. At work we
will usually want a style that is terse and straightforward. But we also want to
avoid being dull. By varying sentence length, construction, and verb use we
may succeed in keeping our reader awake.
3
If the reader notices the language it is getting in the way.
4
If you keep in mind a clear image of your reader (probably fictitious) and
concentrate on explaining what you have to say to him or her, you stand a good
chance of being readable. But if you think only of your subject, you risk being
Page 11 of 35
abc
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
turgid and incomprehensible. “The crucial test of a person’s knowledge is
whether they can make it intelligible to others” – Bruce Cooper [4].
5
Never start writing a sentence before getting into your head the whole of the
idea you want to communicate. Then say it neatly. Muddled writing usually
stems from muddled thought. Good writing requires clear forward thinking,
and is hard work.
To be more specific, what should we aim for?
•
•
•
•
•
Simplicity
Shortness
Strength
Clarity
Correctness (grammar, punctuation)
Page 12 of 35
abc
5
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
Simplicity
Avoid the flatulent, self-satisfied style.
Prefer the familiar word to the far-fetched.
Prefer the concrete word to the abstract.
Prefer the single word to the circumlocution.
Prefer the short word to the long.
– H W Fowler [5].
5.1
At word level
As a general rule, use short words rather than long ones, concrete ones rather than
abstract ones.
So use:
use
large
best
ask
start
rather than
utilise
significant (unless it means “important”)
optimum
request
commence
Distrust words ending in -ance, -ment, -ity, -tion, etc. These abstract words do have
their place, but they are essentially dull. If you find yourself using them much, you
have probably fallen into a dreary, wordy style and have stopped thinking about your
friendly reader.
You do not speak like this to somebody you know:
Its practicality depends essentially on there being a mutuality of
capability and interest.
The availability of skilled software engineers is extremely limited.
Instead say:
To make it work, both sides must be able and willing.
Skilled software engineers are scarce.
“Facilitate”, “necessitate”, “unavailability” are all examples of the flatulent, selfsatisfied style. Often two short words are more human than one long one. Or swap
the whole sentence round to avoid the problem.
5.1.1
Jargon
Jargon is fine as a shorthand between people who understand it, but useless and
irritating to a person who does not. Your document is successful if your reader
understands it, easily and efficiently, but not otherwise. You must consider who your
reader is. If you are writing to a person in the know, use jargon because this will
make communication easier. Otherwise do not, since it will make communication
harder. It is sometimes difficult to spot jargon in your own speech. Often the greatest
experts are the feeblest communicators.
Page 13 of 35
abc
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
This example, if addressed to chemists, shows a sensible use of jargon:
In America Dr H C Brown was trying to synthesise useful high
temperature
resistant
perfluoro-alkyl-triazine
polymers
by
homopolymerization of perfluoroalkylene diadimines or by
copolymerization of these monomers with perfluoroalkyl monoadimines.
In this example from The Lancet the writer is just showing off:
Experiments are described which demonstrate that in normal individuals
the lowest concentration in which sucrose can be detected by means of
gustation differs from the lowest concentration in which sucrose (in the
amount employed) has to be ingested in order to produce a demonstrable
increase in olfactory acuity and a noteworthy conversion of sensations
interpreted as a desire for food into sensations interpreted as a satiety
associated with the ingestion of food.
This is how Sir Ernest Gowers would have said it:
Experiments are described which demonstrate that a normal person can
taste sugar in quantities not strong enough to interfere with his sense of
smell or take away his appetite.
And here is a clear description of some technology. It could so easily have been
suffocated in jargon:
The uranium rod in its can, the fuel rod as it is called, is the key
component in a nuclear reactor and is one of the most difficult to design.
Consider the requirements. In order to transmit the heat generated in
the uranium through the metal can to the cooling gas, the can must make
good thermal contact with the uranium on the inside and transfer heat
efficiently to the gas on the outside. At the same time it must not be
corroded either by the gas or by the uranium and, as with everything
inside a reactor core, it must absorb neutrons to the least possible extent.
Finally it must be mechanically strong at the high temperature of
operation, or the weight of uranium inside would cause cracks and the
can would cease to be effective in doing its job – Kenneth Jay, “Calder
Hall”, 1956
5.2
At sentence level
Once again, aim short. As a general guide, keep your average below 20 words. Short
sentences are easier to read. If you think your grammar is weak, avoid long sentences
like the plague!
Long, complex sentences are often hard to understand because they contain several
ideas jumbled together in an illogical order (a problem made even worse if the
sentence is stuffed full of long abstract words). Get your ideas into a logical order.
Then have one main idea per sentence. Your main idea may need qualifying within
the same sentence, but keep the number of subsidiary ideas small.
Page 14 of 35
abc
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
If a sentence is getting out of control, break it into two or three sentences (or into lists
where appropriate).
The following sentence has eight ideas:
Inspection (1) of the stepped bolts (2) that pass through the top boom (3)
of the centre section spar (4) into the fuselage frame (5) adjacent to the
roof end (6) was attempted (7) but was found to be unsatisfactory and
inconclusive (8).
We could split this sentence in various ways to make it less of a mouthful; for
example:
Inspection of the stepped bolts was attempted but was unsatisfactory and
inconclusive. These stepped bolts pass through the top boom of the
central section spar into the fuselage frame near the roof end.
Be compact. Don’t strain your reader’s memory by widely separating parts of a
sentence that are closely related.
Notice that by splitting sentences you may actually increase the overall length. What
matters is that the ideas are presented in a logical (easily absorbed) order and in
manageable packets.
5.2.1
Hunt the verb
The last example illustrates another point. It is not easy to keep track of a sentence if
the verb is too far from the beginning. The whole meaning of a sentence centres on
its verb.
In the example, the reader has to take on board a lot of concepts (stepped bolts, top
booms, section spars, fuselage frames, roof ends) without knowing why he is reading
about them. The main axis of the sentence is that “inspection . . . was attempted”; but
this central point occurs far too late. The reader has to store all the detail in his mind
until he reaches the nub of the sentence. The result is illogical and tiring.
This is a rotten trick, widely employed by thoughtless writers. Keep the verb near the
beginning!
5.3
At paragraph level
Short paragraphs are easier to read and more inviting. Correct paragraphing helps
easy assimilation of information. Logically each paragraph should treat one subject.
But if one subject is long, break the paragraph in spite of the logic. Do not be
frightened of very short paragraphs only a few words long.
Page 15 of 35
abc
5.4
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
The fog index
Are you making your reader’s life difficult? Apply this test.
1
Choose a chunk of text 100 words long.
2
Count the number of sentences. Treat as one sentence:


a part sentence (at the beginning or end)
each item of a list
3
Divide the number of sentences into 100 to give average sentence length.
4
Count the words of three or more syllables. Do not include:



words starting with a capital letter,
words which only qualify because they are in the past tense or plural,
technical words which cannot sensibly be replaced.
5
Add the results of steps 3 and 4.
6
Multiply that sum by 0.4 and round it to the nearest whole number.
7
Add 5 to this number to give the reading age a reader needs to understand the
text.
For good technical writing, aim for a reading age of 15-20 years.
5.5
An American example
The original:
Such preparations shall be made as will completely obscure all Federal
buildings occupied by the Federal government during an air raid for any
period of time from visibility by reason of internal or external
illumination. Such obscuration may be obtained either by blackout
construction or by terminating illumination.
This will, of course, require that in building areas in which production
must continue during a blackout, construction be provided, that internal
illumination may continue. Other areas, whether or not occupied by
personnel, may be obscured by terminating the illumination.
Rewritten by Franklin D Roosevelt:
In buildings where work will have to keep going, put something across
the windows. In buildings where work can be stopped for a while, turn
out the lights.
Page 16 of 35
abc
6
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
Shortness
Readers prefer short documents. We have already looked at short words and at
cutting sentences into manageable lengths; now let us clear out meaningless dross.
Simple ideas can be transformed into a tedious thicket by adding an assortment of
verbal clutter.
6.1
Stretched-out sentence openers
It ..... that
It was generally agreed that
It is to be expected that
What ..... is
What I have been attempting to do is
What we need to aim for is
Words like these usually add nothing. They are useful in speech as a way of wasting
time while you think what you are actually going to say. But in writing you do not
need to waste time. Cut it out and save paper.
Delete: What we need to aim for is greater flexibility.
Say: We need greater flexibility
Delete: It should be noted that this solution has its own problems.
Say: This solution has its own problems
6.2
Repetition
This is another source of clutter:
The control board operates in two basic modes, one mode being the
normal mode and the other mode being the buffered mode.
Say:
The control board operates in two basic modes, normal and buffered.
6.3
Padding
Don’t waste paper by filling out your sentences with words that contribute nothing.
Try crossing them out. Does it make any difference?
Here are some words which probably contribute nothing (depending on context):
unfilled vacancy (what is a filled vacancy?)
integral part (a non-integral part?)
active consideration (passive consideration?)
definite decision (an indefinite decision?)
Page 17 of 35
abc
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
there is no cause for undue alarm
(there is no cause for alarm for which there is no cause?)
Here are some words which may mean nothing because they have not been defined:
unduly (by what test?)
relatively (relative to what?)
comparatively (compared with what?)
In general avoid adjectives which only describe degree:
The proposal met with (considerable) opposition and is in (great) danger
of rejection.
If adjectives actually add meaning, that is a different matter:
The proposal met with (bad-tempered) opposition and is in (imminent)
danger of rejection.
Here are some longer examples of padding:
The pulleys should be rotated in a clockwise direction.
Discussion of this question is irrelevant as far as present plans are
concerned.
Say:
Rotate the pulleys clockwise.
This question is irrelevant to present plans.
In this example the words in brackets do not add enough meaning to earn their keep:
The completed report (now being prepared and) covering three years of
intensive activity over the greater part of Scotland (with its factual
matter, conclusions and recommendations) will be (an) invaluable
(document) to the new Tourist Board in planning (the provision of future)
tourist facilities.
Instead we get:
The completed report, covering three years of intensive activity over the
greater part of Scotland, will be invaluable to the new Tourist Board in
planning tourist facilities.
If it doesn’t add meaning, cross it out!
Page 18 of 35
abc
7
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
Lists
In the last two sections we looked at ways of simplifying and shortening sentences.
Lists provide another technique for achieving these aims. However lists are a subject
in themselves, and deserve their own section.
7.1
Introduction
In project and technical documents, it is often helpful to give information in the form
of lists, rather than as solid paragraphs of text. Lists have three obvious merits:
•
Clarity. A list clarifies the structure of your argument, when you are
presenting a series of parallel points, or a sequence of steps.
•
Identification. You can number the items and refer to them from elsewhere in
the document, or from a different document.
•
Attractiveness. A mix of text and lists usually gives a more pleasing look to
the page. (You should be trying to please your reader, shouldn’t you?)
This paper offers a few guidelines on the use of lists. You may not agree with
everything.
7.2
First an example
This example shows how lists can clarify thought. The original version appeared as
text, as follows:
The first step involves looking at the use to which the system will be put
and the level of understanding we have of it; this will allow us to choose
an overall approach to the development. By looking at the type of system
to be built we are led on to the choice of appropriate technologies for
such a development, which in turn will define the training required, the
acquisitions which have to made, and how the system will be maintained
after delivery.
This train of thought might be best presented in a flow diagram. We can improve it
by breaking it down:
First we must analyse the expected use of the system. Then we can:
•
select an overall approach to the development,
•
choose appropriate technologies.
Then we can decide:
•
what training we need,
•
what hardware and software we need,
•
how the system will be maintained after delivery.
This is not the only way to restructure the example. Notice that I have omitted “the
level of understanding we have of it”. The discipline of structuring the ideas logically
made me realise that I didn’t know what this means.
Page 19 of 35
abc
7.3
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
The mechanics of lists
Let’s consider lists under the following headings:
1 The lead-in
2 The list items
3 Punctuation
7.3.1
The lead-in
Every list should have an introduction which reveals what the list is. Don’t leave the
reader thinking “What is this a list of?”.
The introductory words may consist of:

one or more complete sentences, ending with a full stop;

an incomplete sentence, which is completed by the list items.
The list must have parallel structure: each item in the list must make sense on its own
when read with the introductory words; and each item must have the same format.
Here is a poor example:
Users wanted some change to the format of reports:
•
Add description of each part number
•
Change to daily reporting
•
Index not changing properly
•
First line on some pages not correctly displayed
The first two of these are demands (Add! Change!); the second two are limp verbless
comments. Try reading the introductory words with the fourth item only.
Here is a better version:
Users wanted to improve reports by:
•
adding a description of each part number,
•
changing to daily reporting,
•
making the index change properly,
•
displaying the first line of each page correctly.
Notice that this version has parallel structure: each item on its own provides a
satisfactory conclusion to the introductory words, because each item starts with an “ing” word.
7.3.2
The list items
The items in a list can start with:





a word or phrase (preferably emboldened or italicised),
a number,
a letter,
a bullet or other symbol,
a dash.
Page 20 of 35
abc
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
Here are my suggestions.
•
Words: Use an emboldened keyword or phrase for long items, where that will
help readers to glance down the list, seeing immediately the subject of each
item. This technique can be used in a bulleted list, or in a “hanging” list with
the keyword in an enlarged left-hand margin. Consider using emboldened
keywords in shorter list items too; and even if you do not provide a keyword at
the start, it can be helpful to embolden a keyword in the body of each list item.
•
Numbers and Letters: Use numbers or letters in the following situations:
•
a
where the order matters, for example when describing the steps of a
procedure (numbers are best here);
b
where you will need to refer to the list from elsewhere in the document
(letters are best here, to avoid any confusion with the section numbers);
c
where you, or other people, will need to refer to these items from another
document or in conversation – for example a list of user requirements;
d
where you are listing the headings of later parts of the document (make
sure that the numbering of the parts matches the list).
e
where the list is confusingly long, with more than (say) six items.
Bullets: Apart from these specific uses for numbers and letters, bullets are
arguably neater. In a document with many short, numbered sections, numbers
and letters tend to sit uneasily with the section numbering. This is a matter of
taste.
Treat bullets as the norm for short lists, where no external reference will arise.
Certainly any need for external identification must be paramount.
•
Dashes: These are good for nested lists (a list within one of the items of a
parent list).
Three general points:
7.3.3
•
Whatever you choose, try to be consistent throughout your document. Don’t
swap arbitrarily between bullets and dashes for straightforward un-nested lists.
For example, this document uses bullets where all the list items apply, and
dashes where the list items indicate options or choices.
•
Use contrasting styles for nested lists. If the parent list has bullets, use dashes
for the second-level items. If the parent list has numbers, and you also want to
number the second level, try lower-case letters.
•
If there are more than seven items in a bulleted list, consider grouping the items
under headings (ie create a nested list).
Punctuation
The punctuation of lists causes much unproductive discussion. Strictly you should
respect the integrity of normal sentence structure.
Page 21 of 35
abc
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
a
If the introductory words are an incomplete sentence, the sentence doesn’t end
until the end of the list. Each item starts with a lower-case letter and ends with
a comma (if list items are short), or a semi-colon (if list items are long).
b
If the introductory words form a complete sentence in themselves, ending with
a full stop, each list item will also form one or more complete sentences,
starting with an upper-case letter, and ending with a full stop.
I believe that these two alternatives are strictly correct, and provide a safe rule. In practice, I
often bend the rule in various ways, relying on my own judgement:
c
I sometimes use a colon to introduce a list, even when the lead-in was a
complete sentence (as in this example).
d
Where list items consist of single words or very short phrases, I think they often
look better without any punctuation at all, especially in less formal documents
(see the first list in section 7.3).
If you start a list of type (a), and find that it gets longer than you expected, and strains
your ability to punctuate it as a single sentence, go back and alter the lead-in so that it
becomes a list of type (b). Certainly if you find yourself starting new sentences
within a list item, you should also be commencing each item as a new sentence.
Always use punctuation consistently within one list. And always use list styles
consistently within one document.
7.4
Finally
Beware ambiguity
It is horribly easy to fall into a nasty trap. Listed items may be either cumulative or
alternatives. Look at this:
We will limit recruitment to:

graduates in a computing discipline,

people with at least two years’ industrial experience,

people with a
developments.
good
knowledge
of
relational
database
Does this mean that we will take a non-graduate who has one of the other attributes?
I could avoid this by changing the lead-in (“We will recruit only those applicants who
satisfy three criteria:”). There are various other ways of doing it; the important point
is to spot the ambiguity.
Don’t overdo it
Don’t get carried away.
A surfeit of lists can irritate. This section deliberately uses lists to illustrate its
messages; for ordinary purposes it probably has too many.
Don’t use lists nested to more than two levels, unless you really, really, must.
Page 22 of 35
abc
8
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
Strength
Don’t Blame Me; I Don’t Really Mean All This
Do you write in a direct, convincing way as if you mean it and are keen to enthuse
your reader? Or are you uninterested, bored, and wanting to be as invisible as
possible? Have you got a relationship with your reader? Will your reader warm to
your subject?
8.1
Conviction
People often want to avoid responsibility for what they say. Perhaps:

they are not completely sure they are right,

it would not be diplomatic to speak too plainly,

or they are speaking on behalf of a group (eg a project team) and want to be
anonymous.
These aims may sometimes be sound, but not often. Be positive whenever possible.
There is something to be said for being bold and wrong, rather than so hedged about
by qualifications that nobody is really sure what you are saying. If your document
will be reviewed, try making blunt statements accompanied by an “(is this correct?)”
flag, so that you can use the review to clarify the situation.
If you try to achieve these aims by writing in a roundabout, impersonal style that
carefully avoids making any direct statement, you will just produce a fog. You can
achieve them in other ways and still write clearly. If you are speaking for a group of
people, use “we” and carry on making clear statements.
Here is an example of somebody trying to avoid saying what has to be said:
XYZ has recently given consideration to the sending of Christmas cards
and, although it is certainly not without its pleasant side, we have
decided regretfully to discontinue the sending of Christmas cards from
this year. I am sure that you will appreciate that the warmth of the
feelings of all in the division who have had, and are having, dealings
with you is undiminished, and that as in the past, but henceforth silently,
our good wishes will be with you at this time of year.
Who does this fool? Why not just say:
This year we have decided to discontinue our practice of sending
Christmas cards. We should, as ever, like to wish you the compliments of
the season.
Let us look at some of the ingredients of “weak” language.
Page 23 of 35
abc
8.2
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
The passive voice
This is the classic way of removing personalities from documents. It is horrendously
over-used.
The active voice uses a strong structure: subject-verb-object:
Tom kicked Fido
The passive voice uses a weak structure: object-verb-subject:
Fido was kicked by Tom
The active voice is simpler and more normal in speech. The passive has some
valuable uses (for example when it really is important to remove personalities from a
document), and it sometimes gives a subtly different meaning.
The passive voice is often badly over-used in writing. It:
•
gets tedious, heavy-going, and produces no excitement whatsoever;
•
causes sentences to become more complicated;
•
leads to ambiguity.
Here are some examples of tedium:
A request to allow mass updating of the database was submitted by Len
Smith.
The selection of this operation is made automatically by the software if
there is no intervention by the operator. (yawn)
This chapter describes how a design in ELLA may be partitioned and
integrated using EASE.
A design is partitioned by compiling
declarations into separate work areas called contexts and is integrated
by sharing declarations between contexts in a controlled manner. A
declaration is shared by exporting it from one context and importing it to
another; this is explained and illustrated by an example. A facility is
introduced which checks that all the appropriate imports and exports
have been made.
Compound contexts which allow alternative
descriptions of a piece of hardware to be imported into the same context
but simulated independently are described and illustrated by a second
example. (zzzzzzzzzzzz)
People often use the passive construction in order to be completely impersonal. But
why? If you are trying to explain something complex why make life even harder by
twisting every sentence back on itself? Surely it is acceptable to say:
In this chapter we describe how to partition a design . . . You partition a
design by compiling declarations . . .
More seriously, the passive construction easily leads to ambiguity, because it omits
the subject of the sentence (the person or thing that does whatever is indicated by the
verb). Look at this:
Page 24 of 35
abc
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
If a report has been suppressed, or a follow-up report has been
submitted, a new report will only be scheduled if further data was
received after the last report was suppressed or submitted.
This is dreadful. The problem is that we never know who (or what) is suppressing,
submitting, scheduling, or receiving the reports. Is it the system? a user? a person
elsewhere in the organisation? The active voice will clarify this perfectly:
If the user has suppressed a report, or submitted a follow-up report, the
system will not schedule a new report until the database receives further
data since the suppression or follow-up.
In descriptions of this type, don’t be frightened of making “the system” a personality
which takes an active part in the process being described:
The system prompts the user to enter values . . . It validates these values . . .
You can vary the style from sentence to sentence if it is getting repetitive. There is
nearly always a choice of ways to state an idea:
In this report X is examined and Y is evaluated. This report examines X
and evaluates Y. In this report we examine X and evaluate Y.
The requirements were studied and it was found... We studied the
requirements and found... An examination of the requirements showed...
So:
•
•
avoid the trap of thinking that writing must sound distantly impersonal
vary the construction to stop your writing getting laborious.
And remember that you are talking to a person.
8.3
Instructions
You can either direct:
Unscrew the cap from the cylinder. Remove the washer. Put back the
cap.
or describe:
The washer can be removed by unscrewing the cap from the cylinder.
The cap should be put back.
The second method tends to be longer and less clear, partly because it is too easy to
get drawn into using passive constructions and an impersonal style.
If you do decide to go for the descriptive method, you can still cut down on the
passive by addressing the reader directly:
You can remove the washer by unscrewing the bottle cap, but you must
put back the cap.
Page 25 of 35
abc
8.4
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
Weak verbs
Verbs often atrophy, leaving a dull, uninspiring read.
8.4.1
Dead verbs
People often turn good straightforward verbs into strings of words.
Table 1.3 gives a listing of the special codes.
We will conduct an inspection of the equipment and make an evaluation
of its safety.
Instead say:
Table 1.3 lists the special codes.
We will inspect the equipment and evaluate its safety.
8.4.2
The verb “to be”
If you use “is/are/was/were” too much, the effect becomes lifeless, and resembles a
string of algebraic formulae: “X is Y”; < abstract concept 1 > is < abstract concept 2 > .
The main reason for this is the requirement for a faster response time.
The necessity of this task was a very important lesson to us.
A useful application of Gray codes is in connection with position
transducers.
The impression or illusion of never keeping the user waiting is required.
A specific requirement is that the redrawing time on screen for a simple
network diagram is at most 500ms. Also required is that the screen
motion be as smooth as possible. Consistency of response is required.
Response is also discussed in Section 5.
Instead use different verbs. You have thousands to choose from. For example:
This arises (flows, results) mainly from the requirement for a faster
response time. This originates mainly in the requirement for a faster
response time.
The need for this task taught us a lot. We found the need for this task
instructive.
Gray codes can usefully be applied to position transducers. Position
transducers provide a useful application for Gray codes.
Page 26 of 35
abc
8.5
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
Redundant words
Resist the temptation to wrap every statement in meaning-deadening cotton wool.
Words like: quite, rather, considerable, relatively.
Phrases like: it might be thought that; it can be established that; there is a possibility
that.
Make bold statements. Don’t mince. Try crossing words out and see if the meaning
changes.
8.6
Variety, the spice of life
We have examined a number of habits that tend to take all the punch out of written
communication. The point is that if every sentence drones on in the form: “Blah blah
blah is blah blah blah”, and is full of long words and involved, impersonal
constructions, even the keenest reader will flag. Use different word orders. Have
some longish sentences, and several shorter ones. Bang in an occasional very short
one. It’s easy. Don’t keep flogging the same little group of worn-out verbs. Every
word must pull its weight. Don’t be frightened to use the dictionary or a dictionary of
synonyms.
9
Clarity
This topic overlaps previous ones. If we succeed in shortening and simplifying, there
is less room for muddle. Just a few key topics then . . .
9.1
Ambiguity
Ambiguity is hard to spot in your own writing because you know perfectly well what
you mean and make the mental leaps necessary to select the correct meaning. Your
reader can only rely on the little black squiggles on the paper.
Ambiguity often arises when the relationship of different parts of a sentence is in
doubt:
If the baby does not thrive on cold milk, boil it.
(a famous example – what does “it” refer to?)
It is forbidden to wear headgear or any other article which can cause
injury to other players.
(what does the “which” clause refer to? – can I wear a towelling
headband or not?)
His disease can only be alleviated by an operation.
(the word “only” is often misplaced – is he going to recover or not?)
Page 27 of 35
abc
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
No child shall be employed on any weekday when the school is not open
for a longer period than four hours.
(these words are in the wrong order.)
Mistakes like these can be cured sometimes by re-arranging the order, sometimes by
adding punctuation, and sometimes by rewriting.
You may be able to see ambiguities in your writing if you read it again, in a critical
frame of mind, after a gap. Otherwise you will have to rely on others spotting it.
Ambiguity is especially insidious when the reader selects the wrong meaning without
even noticing that there was a choice.
9.2
Presenting ideas in a logical sequence
It is too easy to start writing a new sentence by writing down the first idea that comes
into your head, and then to lurch from one qualifying statement to another. The
sentence rambles and the reader loses the point of it. To talk logically you have to
stop first and thin. Start with the idea which is logically first, not the one which
comes into your head first. We have already looked at some examples in
“Simplicity”. Here is an example of a sentence with a complex cluster of seven ideas.
On special jobs (1) where the normal cutting oils will not suffice (2) due
to extremely heavy cutting pressure, (3) for example breaching of high
tensile steel, (4) to produce the finish required (5) this oil is used (6)
although it is extremely expensive. (7)
Don’t have too many ideas in one sentence. Break it into separate sentences even if
you have to say one bit twice:
On special jobs (such as the breaching of high tensile steel) where
extremely heavy cutting pressures arise, the normal cutting oils are not
good enough. We therefore use this extremely expensive oil, because it
gives the finish required.
9.3
Vague words
Some words get over-used because they are attractively vague and allow the writer to
get away without having to think too precisely.
“Involve” is one of these.
The solution to this problem involves several inputs:
(is this list going to be comprehensive?)
During this time he was extensively involved with formal methods.
(used? studied? taught?)
Praxis Critical Systems is involved in an investigation into...
(taking part in a collaborative one? carrying out its own? providing
money for?)
Page 28 of 35
abc
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
“Affect” is another.
The building work has been affected by the weather.
(hindered? brought to a standstill? the materials have been damaged?)
9.4
Too condensed?
We have stressed the benefits of shortness; but it is possible to make your meaning
less clear by cramming too much meaning into too few words.
Design should be more calculatedly goal-directed.
Say: Our designers should pay more attention to what we are trying to
achieve.
This might mean either mandatory (though flexible) minimum liquidity
ratios, or a once-for-all sterilising of excess ban liquidity.
Who knows what this means?
10
Correctness: Grammar and Punctuation
10.1
Grammar
Grammar is the craft of establishing, without ambiguity, the proper
logical connections between words and groups of words, and making
sure that the force of any particular connection does not carry further
than intended. – Letter to the Times Newspaper, 30/12/89
This is a succinct and simple explanation of why grammar is useful. Grammar is
surprisingly logical. It is not a fixed body of rules: grammarians disagree and customs
change. It is less important than expressing yourself clearly. George Orwell said:
Correct grammar and syntax are of no importance so long as one makes
one’s meaning clear.
But correctness does help in two ways:
10.2
•
it increases clarity (because logical) and reduces the risk of ambiguity;
•
unfortunately readers often see grammatical “mistakes”, and spelling mistakes,
as a sign of poor intelligence, and consequently take less notice of what is said.
Some tips on grammar
1
Make sure you know where the verb is. Is it hidden too near the end of a long
rambling sentence? If it consists of more than one word, are the parts spread too
far?
Page 29 of 35
abc
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
If you have any difficulty with the new system, please do not hesitate to let Mr A
Q Hegarty-Smith, Assistant Environmental Health Manager (Manual
Services), know.
If you have any difficulty with the new system, contact Mr H-S...
See also the example in Section 9.2.
10.3
2
Identify subject and object. Is the subject singular or plural? Does the verb
match? See Common Howler 10.3.6 below.
3
Make sure that all parts of the sentence are tied together properly. Are related
parts near enough together? Is it clear what subordinate clauses refer to? If
nouns are replaced by pronouns, is it clear what they refer to? See Section 9.1.
Common grammatical howlers
This section lists some of our favourite howlers. It is only a selection; there are many
more.
10.3.1
Apostrophes
They indicate possession, not plurality. (Rachel’s VDUs)
This rule has one exception – its. This is because it’s means “it is” and the apostrophe
marks a missing letter – see below.
When the possessor is singular use 's. When plural use s'. (boy’s, boys’)
When the possessor is singular but ends in -s you have a choice. (Jones's shop or
Jones' shop). But be consistent.
Apostrophes are also used to mark missing letters. (Don’t, you’ll, it’s)
10.3.2
Praxis Critical Systems
A singular beast full of plural people (Praxis Critical Systems is; we in Praxis Critical
Systems are).
10.3.3
Affect and effect
As a verb affect means “have an impact on”, and effect means “bring about”.
10.3.4
Disconnected clauses
Sometimes ideas in a sentence get so displaced from their logical place that the
resulting nonsense is considered ungrammatical. In this example, the subject of the
sentence (‘I’) has vanished from its vital place after the comma:
Dear Mr Bean,
As Finance Director of a large company myself, the ability of the
company to react to market changes and to maintain profits is of vital
interest to me and the key to the company’s business strategy.
Page 30 of 35
abc
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
An alternative:
Dear Mr Bean,
As Finance Director of a large company, I know how vital it is that the
company reacts to market changes and maintains profits. This is key to
the company’s business strategy.
10.3.5
Parallel construction
When presenting ideas in parallel, for example:
both <...> and <...>
either <...> or <...>,
make sure the bits in brackets are true substitutes. Try swapping them.
We must either make sure that we can provide sufficient resources for
this project, or we should not take it on.
This example can be cured in two ways:

by putting “either” at the beginning of the sentence,

or by omitting “we should”.
10.3.6
Singular and plural verbs
If you let a verb get too far from its subject, you may forget what it refers to and
accidentally make it plural instead of singular, or vice versa:
His refusal to submit to sustained pressures on mind and spirit were
worthy of the highest traditions of journalism.
Public administration and management in central government has stood
up to these strains.
The same thing can be either a singular or a plural concept. The following examples
are all thought to be correct:
A committee was appointed to...
The committee were unable to agree.
Bread and butter is good for you.
Bread and butter are good for you.
(these two do not mean the same thing)
There are a large number of permutations.
(we are thinking more of the permutations than the number)
The number of permutations is large.
(here emphasis is on the number – it occupies a prominent place in the
sentence and a plural verb would sound odd)
There is a wide choice of permutations.
(we are definitely thinking of the choice)
Page 31 of 35
abc
10.3.7
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
Split infinitives
These are not “wrong”, but many people find them ugly. And some people definitely
set themselves up as “split-infinitive censors”. Unfortunately, while this attitude lasts,
writers who use them risk not being taken as seriously as they might like. For this
reason it is probably safer to avoid them, except where efforts to avoid them produce
an even uglier result!
Here is an exciting example:
The tenant hereby agrees:
i
to pay the rent;
ii to properly clean all the windows;
iii to at all times properly empty all closets;
iv to immediately any litter or disorder shall have been made by him
or for his purpose on the staircase or landings or any other part of
the said building or garden remove the same.
10.3.8
Double negatives
Occasionally a double negative can give a useful shade of meaning. For example “not
uncommon” does not say the same as “common”; neither does “not without merit”
coincide with “meritorious”. In most cases, however, they simply set a puzzle for the
reader, who may have to stop and work out laboriously whether the meaning is
positive or negative.
10.4
Punctuation
It is a mistake to think of punctuation as a set of rules which you either know or do
not know. Different experts will quote different “rules” and some say that there are no
rules. It is more a matter of custom, and customs change rapidly.
But punctuation should be used logically if it is to be helpful. It provides a way of
breaking up sentences into little packets of meaning so that the reader’s eye can easily
see the structure. Thus it helps to avoid ambiguity. Common sense usually works.
The following can be made to convey meaning if carefully punctuated:
John where Jack had had had had had had had had had had had the
examiner’s approval.
10.4.1
Commas
They give a slight pause and are the usual way of dividing one idea from another
within a sentence.
Beware of using just a comma to separate what are really two sentences – a very
common error. For example, this is wrong:
The majority of our clients are based in Northern Europe, we are wellpositioned to respond to local market conditions.
Page 32 of 35
abc
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
These are two sentences. If you must join them, use a semi-colon. The comma is
quite wrong.
Commas can be used singly or in pairs (like a pair of brackets) to divide a sentence
into its component clauses.
Sometimes commas simply help the eye, but at other times they change the meaning
or alter the emphasis:
It is forbidden to wear headgear, or any other article, which can cause
injury to other players. (compare this with the version given in
section 9.1)
The documents, which have been put in ring binders, were checked by
Jane.
The documents which have been put in ring binders were checked by
Jane.
He was apparently willing to support your case. (fairly certain)
He was, apparently, willing to support your case. (more doubt)
When using commas to place an idea in parenthesis remember to complete the pair.
This kind of carelessness is common. It is like having one bracket. The following
sentence should have two commas, or none at all:
He was, apparently willing to support your case.
10.4.2
Semi-colons
People used to programming conventions may think of semi-colons as marking the
end of a unit of thought. In written English that job is done by the full stop, with
more minor divisions marked by a comma. This leaves little room for the poor old
semi-colon. In fact some people think it is best avoided altogether; it is certainly
possible to do without it.
However, there are occasions when a semi-colon does a useful job. It provides a
break within a sentence, more pronounced than a comma. Hence its is useful in lists
(see section 7). In general, we recommend using short sentences separated, of course,
by full stops. However you may sometimes find that this gives too disjointed a result,
and that two closely linked sentences would be better fused with a semi-colon:
The next candidate did not impress; he seemed scarcely able to write
clear English.
10.4.3
Colons
Avoid trouble by reserving these for introductions to lists.
10.4.4
Quotation marks
It is tempting to litter a document with words and phrases in quotation marks. There
is nothing wrong with this, except ugliness. Keep quotation marks for:
Page 33 of 35
abc
10.4.5
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
•
genuine quotations from other people;
•
allegations (supposedly “the most advanced” technology in the marketplace);
•
slang;
•
reserved words (or put them in italics or bold).
Spelling
It is not really practicable to give generalised advice, except:
•
read widely,
•
learn Latin at school,
•
refer frequently to a dictionary and/or spelling-checker (but remember that their
are sum errors witch a spelling cheque won’t fined).
Finally, here is a short list of words which are frequently misspelled:
omission
amendment
supersede
correspondence
accommodation
Page 34 of 35
abc
Technical Writing Guide
Guide to Technical Writing: (2) Writing Good English
S.Q1000.90.3
Issue: 1.0
Document Control and References
Praxis Critical Systems Limited, 20 Manvers Street, Bath BA1 1PX, UK.
Copyright  Praxis Critical Systems Limited 1998. All rights reserved.
Changes history
Issue 0.1 (9th March 1998): The first Praxis Critical Systems’ issue, adapted from
the Praxis plc issue (reference N054.40.2) which was written by
Paul Newman.
Issue 1.0 (11th March 1998): A definitive issue, following inspection by and
incorporating comments from the Quality Manager.
Changes forecast
The document will be updated as required.
Document references
1
The Praxis Critical Systems Standard Document, S.Q1000.4.3
2
Guide to Technical Writing: (1) The Document Lifecycle, S.Q1000.90.2
3
Sir Ernest Gowers: The Complete Plain Words. Penguin ISBN 014 051199 7
4
Bruce Cooper: Writing Technical Reports. Penguin ISBN 014 013550 2
5
H W Fowler: Fowler’s Modern English Usage.
ISBN 019 281389 7
Oxford Univ Press
Page 35 of 35