Work

Principles of Good Technical Writing

Home \ Work \ Principles of Technical Writing

Contents
Introduction
Sentence and Paragraph Length
Words to Avoid
Unnecessary Words
Using Nouns Instead of Verbs
Active Versus Passive
Personal Versus Impersonal
Common Mistakes in Writing
Writing Numbers

Introduction

Always have a specific reader in mind and assume that reader is intelligent but uninformed. It may be useful to state the reader profile up front.

Before writing decide what the exact purpose of the report is. Make sure that every sentence makes a contribution to that purpose, and makes it at the right time.
Use language that is simple, concrete, and familiar.
At the beginning and end of every section check your writing according to this principle: first tell your readers what you're going to tell them, then tell them it, and finally tell them what you told them.
Make your report attractive to look at, but do not add meaningless frills.

Other General tips

Keep a good dictionary and thesaurus beside you when you're writing. Before using a word that sounds good, but whose meaning you're unsure of, check it in the dictionary.
Once you've completed a first draft of your report read it through carefully, trying to put yourself in the shoes of your potential readers.
Once you're reasonably confident about the state of your report, ask someone you know to be a good writer to read it before you submit it formally.

Modern school systems produce students who feel ashamed to write short sentences. There is nothing clever about writing long, complex sentences. For technical writing it is simply wrong. Get used to the idea of writing sentences that are reasonably short and simple. In many cases shorter sentences can be achieved by adhering to the following principles:

A sentence should contain a single unit of information. Therefore, avoid compound sentences wherever possible - be on the lookout for words like AND, OR, WHILE which are often used unnecessarily to build a compound sentence.
Check your sentences for faulty construction. Incorrect use of commas is a common cause of poorly constructed and excessively long sentences.
Use parentheses sparingly. Most uses are due to sheer laziness and can be avoided by breaking up the sentence. If you want to retain your reader, NEVER, under any circumstances use nested parentheses.

Example:

Bad: "Time division multiplexed systems are basically much simpler, the combination and separation of channels being affected by timing circuits rather than by filters and inter-channel interference is less dependent on system non-linearities, due to the fact that only one channel is using the common communication medium at any instant."

Good: "Systems multiplexed by time division are much simpler. The channels are combined and separated by timing circuits, not filters. Interference between channels depends less on non-linear features of the system, because only one channel is using the common communication medium at any time."

Learning about some of the principles described below, such as using active rather than passive constructs, will go some way toward helping you shorten your sentences. A paragraph should contain a single coherent idea. It is easier to read a text where paragraphs are not excessively long. You should try always to keep them to less than half a page. On the other hand, successive paragraphs that are very short may also be very difficult to read. Such an approach is often the result of poorly structured thinking. If you need to write a sequence of sentences that each express a different idea then it is usually best to use itemized or bulleted lists instead. The fact that the sentences need to be written in sequence suggests that there is something that relates them. The idea that relates them should be used to introduce the list. As an example, look at the numbered list above.

Words to Avoid

Read this section with care - there are words here that many penalise you for using.

The golden rule on words to avoid is to never use a difficult word or phrase when there's a simple alternative. For example -

utilise (use)
facilitate (help)
at this time (now)
such that (so that)

Colloquialisms/corporate speak are similarly discouraged -

ping (send an email)
push back (resist)
rocking (using/wearing)

Unless you are talking about image synthesis or extraction by melting, never use the verb ‘render’ as in: "The testing strategy rendered it impossible to find all the faults."

A better version of the above sentence is "The testing strategy made it impossible to find all the faults." In other words, if you mean 'make' then just write 'make', and not 'render'. Here are some other examples of commonly used words that have much simpler (and better) alternatives:

Bad	Good
Endeavour	Try
Terminate	End, stop
Dialog	Talk, discuss
Transmit	Send
Demonstrate	Show
Initiate	Begin, start
Assist	Help
Necessitate	Need

In general you should only ever use the 'bad' words here if some special context means it is really necessary to do so. In many cases there is no simple rule for transforming a sentence with unnecessarily long words, but the following examples should give you some idea of the improvements that can be made.

Bad	Good
The precise mechanism responsible for this antagonism cannot be elucidated.	We do not know what causes this antagonism.
With enough ancillary labour to assist...	With enough extra labour to help...
The stability of the process is enhanced by co-operation...	Co-operation improves the stability of the process.

Unnecessary Words

Many sentences contain unnecessary words that repeat an idea already expressed in another word. This wastes space and blunts the message. In many cases unnecessary words are caused by ‘abstract’ words like nature, position, character, condition, situation as the following examples show:

Bad	Good
The product is not of a satisfactory nature.	The product is unsatisfactory.
The product is not of a satisfactory character.	The product is unsatisfactory.
After specification we are in a position to begin detailed design.	After specification we can begin detailed design.
We are now in the situation of being able to begin detailed design.	We can now begin detailed design.

In general you should use such abstract words sparingly, if at all. Often writers use several words for ideas that can be expressed in one. This leads to unnecessarily complex sentences and genuine redundancy as the following examples show:

With Redundancy	Without Redundancy
The printer is located adjacent to the computer.	The printer is next to the computer.
The printer is located in the immediate vicinity of the computer.	The printer is near the computer.
The Jubilee Line is currently operating a good service this afternoon.	The Jubilee Line is currently operating a good service.
This is done by means of inserting an artificial fault.	This is done by inserting an artificial fault.
The reason for the increase in number of faults found was due to an increase in testing.	The number of faults found increased because of an increase in testing.
It is likely that problems will arise with regards to the completion of the specification phase.	You will probably have problems completing the specification phase.
Within a comparatively short period we will be able to finish the design.	We will be able to finish the design soon.

Another common cause of redundant words is when people use so-called modifying words. These often turn out to be meaningless. For example:

Bad		Good
absolutely critical		critical
considerable difficulty		difficulty
utterly wrong		wrong

Similarly, the following words are fine when used with a concrete reference, but in many cases they are not:

appreciable
approximate
comparative

definite
evident
excessive

suitable
fair
negligible

reasonable
relative
undue

Using Nouns Instead of Verbs

One of the worst, but most common, examples of poor writing style is where authors turn verbs into nouns or use abstract nouns rather than active verbs. The following examples show the major improvements you can achieve by getting rid of nasty noun constructions:

Bad	Good
He used to help in the specification of new software.	He used to help specify new software
Text the directions.	Send a text message with the directions.
Measurement of static software properties was performed by the tool.	The tool measured static software properties.
Clicking the icon causes the execution of the program.	Click the icon to execute the program.
The analysis of the software was performed by Fred.	Fred analysed the software.
The testing of the software was carried out by Jane.	Jane tested the software.
It was reported by Jones that method x facilitated the utilisation of inspection techniques by the testing team.	Jones reported that method x helped the testing team use inspection techniques.

The last example (the bad version appeared in a published paper) breaches just about every principle of good writing style. It uses a noun construct instead of a verb and it includes one of the forbidden words (facilitated). However, one of the worst features of this sentence is that it says, "It was reported by Jones" instead of simply "Jones reported". This is a classic example of use of passive rather active constructs. We deal with this in the next section.

Active Versus Passive

Consider the following sentences:

Joe tested the software.
The software was tested by Joe.
Tom threw the ball.
The ball was thrown by Tom.

Both sentences provide identical information. The first and third are in the active voice and the second and fourth in the passive voice. In certain situations it can make sense to use the less natural passive voice. For example, if you really want to stress that a thing was acted on, and then it is reasonable to use the passive style. However, many people routinely use the passive style simply because they believe it is more 'formal' and 'acceptable'. It is not. Using the passive style is the most common reason for poorly structured sentences and it always leads to longer sentences than are necessary. Unless you have a very good reason for the change in emphasis, you should always write in the active style.

The following examples show the improvements of switching from passive to active:

Bad	Good
The report was written by Bloggs, and was found to be excellent.	Bloggs wrote the report, which was excellent.
The values were measured automatically by the control system.	The control system measured the values automatically.
It was reported by the manager that the project was in trouble.	The manager reported that the project was in trouble.

Personal Versus Impersonal

Whether to use personal (first person) or impersonal (third person) style is a subject that causes fierce debate. The most important justification for using first person style is that it is more natural and results in simpler sentences. Poor sentence structure, notably using passive rather than active style, is most commonly caused when authors are forced to write in the third person. Consider the following examples:

Bad	Good
The current research work of the author is also described.	I also describe my current research work.
In the previous report of the authors the rationale for the proposed method was discussed in detail.	We discussed in detail the rationale for the proposed method in our previous report.
However, it was the writer’s belief that this situation should not have occurred.	However, I believed that this situation should not have occurred.
Examination and discussion of the of the results obtained, are necessary before a decision can be taken.	We must examine and discuss the results before we decide.

In many situations avoiding the first person also introduces ambiguity. For example, consider the statement:

"Recent experiments involving formal inspections have resulted in ..."

It is not clear whether the writer is referring to his/her own experiments, other researchers' experiments, or a combination of the two.

Even worse than ambiguity is where use of the third person rather than first introduces genuine uncertainty. For example, consider the following:

"It is not possible to state the exact mode of operation of the drug".

This leaves serious doubts in readers' minds. It might mean that the authors do not know how the drug works, but it might also mean that the operation of the drug is impossible.

One final word about personal versus impersonal writing.

Many authors, who are reluctant to use first person but realise that they cannot write a sentence naturally without it, opt to use the expression 'one' as in "One can conclude from the experiment..." Don't do it. It sounds pompous and ridiculous. If you feel uneasy about saying "I" then say "We".

Common Mistakes in Writing

There are quite a few mistakes that people make day to day. Here are some of the more common ones:

Plural and Singular ACME is always singular. You should always write ACME is, or ACME TECHNOLOGIES is, even though Technologies is plural. You are talking about an organization as a whole, so the company is an entity in itself.
Spelling All spelling should conform to English standards, not American. Therefore: colour, organise and centre are correct. Color, organize, and center are not.
e.g. and i.e. These are both abbreviations and should be treated accordingly with full stops. E.g. is short for exempli gratia – for example. I.e. is short for id est – that is. When in doubt read your sentence with "for example" or "that is" and choose the appropriate shortening. Most times these appear in parentheses.
That vs. which That should be used in a main clause (i.e. a clause with no commas around it), which should be used when the sentence is surrounded by commas. That should be used MORE often than which.
Affect vs. Effect Use effect when you mean bring about or brought about, cause or caused (e.g. He effected a commotion in the crowd). Use effect when you mean result (e.g. What effect did that speech have?). Also use effect whenever any of these words precede it: a, an, the, no, any, take, into (note that these words may be separated from effect by an adjective), e.g. That book had a long-lasting effect on my thinking. Has the medicine produced any noticeable effects? If none of the above fit, use affect.
It's vs. Its It's is short for "it is". Its is the possessive version of an item (e.g. "The chair had its back ripped off")..
Possessives (with 's and s') Possession is often indicated in English by adding 's or ' at the end of the noun indicating the possessor. Singular nouns take 's and irregular plurals take 's. However nouns ending in s (plural or singular) take s'. So:

The car of John = John's car.
The room of the girls = The girls' room.
The sister of Charles = Charles' sister.
The boat of the sailors = The sailors' boat.
The dresses of the women = The women's dresses.
The boat of the sailors = The sailors' boat.
The teacher of the students = The students' teacher.
The fortune of Howard Hughes= Howard Hughes' fortune.

Writing Numbers

There is a set of rules for writing numbers:

The numbers one through ten should be spelled out; use figures for numbers greater than ten. (e.g. I want five copies. He wants 15 copies.)
With a group of related numbers where one number is above 10 in a sentence, write them all in figures. Use words if all related numbers are 10 or below.

Correct: I asked for 5 pencils, not 50.
Inorrect: I asked for five pencils, not 50.

If the numbers are unrelated, then you may use both figures and words. For example: I asked for 30 pencils for my five employees.
Use figures for tables and statistics.
Always spell out simple fractions and use hyphens with them. For example: One-half of the pies have been eaten. A two-thirds majority.
A mixed fraction can be expressed in figures unless it is the first word of a sentence. For example: We expect a 5 ½ percent wage increase. Five and one-half percent was the maximum allowable interest.
The simplest way to express large numbers is best. For example: 4 million pounds OR £4 million OR four million pounds (not £4,000,000). Be careful to be consistent within a sentence.

Correct: You can earn anywhere from £500 to £5,000,000.
Incorrect: You can earn anywhere from £500 to £5 million.

Write decimals in figures. Put a zero (0) in front of a decimal unless the decimal itself begins with a zero. For example: It grew 0.79 of a foot in one year.
When writing large numbers of five or more digits, use a comma where the comma would appear in the figure format. Use the word and only where the decimal point appears in the figure format. For example: £1054.21 (One thousand fifty-four pounds and twenty-one pence); £15,768.13 (Fifteen thousand, seven hundred sixty-eight pounds and thirteen pence).
Hyphenate all compound numbers from twenty-one through ninety-nine. For example: Forty-three people were injured in the train wreck.
Do not hyphenate one hundred, two hundred, etc.

The following examples apply when using dates:

The meeting is scheduled for June 30.
The meeting is scheduled for the 30th of June.
We have tricks played on us on April 1.
The 1st of April scares some people.

Home | < Back Work | ^ Back to top