Technical Writing Guide - International Union of Railways · abc Technical Writing Guide Guide to Technical Writing: (2) Writing Good English S.Q1000.90.3 Issue: 1.0 Page 2 of 35

abc

Technical Writing Guide

Guide to Technical Writing: (2) Writing Good English

S.Q1000.90.3Issue: 1.0

Status: Definitive11th 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

Page 2 of 35

Contents

1 Introduction 4

2 Stop Before You Start 4

3 The Ideas 5 3.1 Ordering your ideas 5 3.2 Completeness in the flow of ideas 6 3.3 Maintaining perspective 9

4 The Words 10

5 Simplicity 13 5.1 At word level 13 5.2 At sentence level 14 5.3 At paragraph level 15 5.4 The fog index 16 5.5 An American example 16

6 Shortness 17 6.1 Stretched-out sentence openers 17 6.2 Repetition 17 6.3 Padding 17

7 Lists 19 7.1 Introduction 19 7.2 First an example 19 7.3 The mechanics of lists 20 7.4 Finally 22

8 Strength 23 8.1 Conviction 23 8.2 The passive voice 24 8.3 Instructions 25 8.4 Weak verbs 26 8.5 Redundant words 27 8.6 Variety, the spice of life 27

9 Clarity 27 9.1 Ambiguity 27 9.2 Presenting ideas in a logical sequence 28 9.3 Vague words 28 9.4 Too condensed? 29

10 Correctness: Grammar and Punctuation 29 10.1 Grammar 29 10.2 Some tips on grammar 29

abc


S.Q1000.90.3 Issue: 1.0

Page 3 of 35

10.3 Common grammatical howlers 30 10.4 Punctuation 32

Document Control and References 35 Changes history 35 Changes forecast 35 Document references 35

abc


S.Q1000.90.3 Issue: 1.0

Page 4 of 35

1 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.

abc


S.Q1000.90.3 Issue: 1.0

Page 5 of 35

3 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:

1 Order, at document level, section level, sentence level

2 Completeness

3 Maintaining perspective

3.1 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.

abc


S.Q1000.90.3 Issue: 1.0

Page 6 of 35

2 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.

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 sub-headings (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 pre-conceived 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.

3.2 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?

abc


S.Q1000.90.3 Issue: 1.0

Page 7 of 35

2 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

abc


S.Q1000.90.3 Issue: 1.0

Page 8 of 35

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.

abc


S.Q1000.90.3 Issue: 1.0

Page 9 of 35

• 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.

3.3 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.

abc


S.Q1000.90.3 Issue: 1.0

Page 10 of 35

4 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 no The writer is obviously very clever no A striking style no Correct grammar, spelling, punctuation yes

Easy to follow yes Seems to make the subject less weighty than you thought yes Holds your interest yes Seems to talk to you personally at your level 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.

abc


S.Q1000.90.3 Issue: 1.0

Page 11 of 35

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

abc


S.Q1000.90.3 Issue: 1.0

Page 12 of 35

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)

abc


S.Q1000.90.3 Issue: 1.0

Page 13 of 35

5 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 rather than utilise large significant (unless it means “important”) best optimum ask request start 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, self-satisfied 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.

abc


S.Q1000.90.3 Issue: 1.0

Page 14 of 35

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.

abc


S.Q1000.90.3 Issue: 1.0

Page 15 of 35

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.

abc


S.Q1000.90.3 Issue: 1.0

Page 16 of 35

5.4 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.

abc


S.Q1000.90.3 Issue: 1.0

Page 17 of 35

6 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?)

abc


S.Q1000.90.3 Issue: 1.0

Page 18 of 35

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!

abc


S.Q1000.90.3 Issue: 1.0

Page 19 of 35

7 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.

abc


S.Q1000.90.3 Issue: 1.0

Page 20 of 35

7.3 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.

abc


S.Q1000.90.3 Issue: 1.0

Page 21 of 35

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:

• 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).

7.3.3 Punctuation

The punctuation of lists causes much unproductive discussion. Strictly you should respect the integrity of normal sentence structure.

abc


S.Q1000.90.3 Issue: 1.0

Page 22 of 35

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 good knowledge of relational database

developments.

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.

abc


S.Q1000.90.3 Issue: 1.0

Page 23 of 35

8 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.

abc


S.Q1000.90.3 Issue: 1.0

Page 24 of 35

8.2 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:

abc


S.Q1000.90.3 Issue: 1.0

Page 25 of 35

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.

abc


S.Q1000.90.3 Issue: 1.0

Page 26 of 35

8.4 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.

abc


S.Q1000.90.3 Issue: 1.0

Page 27 of 35

8.5 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?)

abc


S.Q1000.90.3 Issue: 1.0

Page 28 of 35

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?)

abc


S.Q1000.90.3 Issue: 1.0

Page 29 of 35

“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:

• 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.

10.2 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?

abc


S.Q1000.90.3 Issue: 1.0

Page 30 of 35

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.

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.

10.3 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.

abc


S.Q1000.90.3 Issue: 1.0

Page 31 of 35

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)

abc


S.Q1000.90.3 Issue: 1.0

Page 32 of 35

10.3.7 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 well-positioned to respond to local market conditions.

abc


S.Q1000.90.3 Issue: 1.0

Page 33 of 35

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:

abc


S.Q1000.90.3 Issue: 1.0

Page 34 of 35

• genuine quotations from other people;

• allegations (supposedly “the most advanced” technology in the marketplace);

• slang;

• reserved words (or put them in italics or bold).

10.4.5 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

abc


S.Q1000.90.3 Issue: 1.0

Page 35 of 35

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. Oxford Univ Press ISBN 019 281389 7

Documents

Technical Writing Guide - International Union of Railways · abc Technical Writing Guide Guide to Technical Writing: (2) Writing Good English S.Q1000.90.3 Issue: 1.0 Page 2 of 35