Technical Writing Advice

This page will provide you with hints and tips for more successful technical writing. The information is gleaned from a wide variety of resources, and is based on the style favoured by the Computer Science Department, University of Canterbury.

Overall Style

Technical writing should be concise and precise. Make your writing interesting and readable. It is better to write two short clear sentences than a long, complex one. Your style should help, not hinder, the reader to understand what you are saying.

Writing Technical Documents by Baden Eusen contains some general information on style. An excellent text for Computer Scientists is Writing for Computer Science by Justin Zobel.

Avoid the overuse of:

Nominalisations - converting a verb into a noun, e.g. writing ‘undertake a study of’ instead of ‘study’

Circumlocution - being verbose, e.g. writing ‘despite the fact that’ instead of ‘although’.

Tautologies - saying the same thing twice, e.g. absolutely unique.

Every style guide seems to have a different opinion on certain topics. Some of the best general style guides available are: Strunk and White The Elements of Style, The Cambridge Australian English Style Guide, and the Style Book. A guide for New Zealand writers and editors.

Punctuation

The correct use of punctuation ensures your work is easy to read. There are a number of very good style guides available to help you with this. The Style Book. A guide for New Zealand writers and editors. revised and expanded by Derek Wallace and Janet Hughes is particularly useful.

Apostrophes

Expand contractions in technical writing, e.g. can’t should be written cannot.

Use apostrophes to indicate possession, e.g. Bell’s method.

Watch out for its and it’s. Only use it’s if you mean it is. (Its indicates possession, e.g. the dog was big, its collar was red.)

Quotation Marks

A variety of opinion exists on the use of quotation marks. This is the suggested style for the COSC Department.

Double quotes are used for primary quotations. Single quotes are used for secondary quotations (quotations within quotations) or where you wish to emphasise a word (an alternative to this could be to use a different style, e.g. italics or bold face).

Conventions on where to place punctuation symbols are as follows: If the quotation or bracketed phrase occurs as part of a sentence, the punctuation goes outside the quote mark or bracket. e.g. One of the reserved words in C is ‘for’. If the entire sentence is quoted, or enclosed within parentheses, the punctuation goes inside. e.g. “There are no dull subjects, only dull minds.” (Note that this is a sentence.)

Grammar

Do you have problems constructing sentences? Do you want to understand more about complex sentences, adverbial phrases and misplaced modifiers? Grammar Smart by The Princeton Review contains all you ever needed to know but were afraid to ask.

Make sure the meaning of your sentence is clear. Avoid misplaced modifiers. Subject/verb agreement is particularly important. Singular subjects take singular verbs and plural subjects take plural verbs.

English for speakers of other languages

(ESOL)

The use of articles, and prepositions are two of the most difficult areas for ESOL students. Practical English Usage by Michael Swan is one of the best books to comprehensively cover almost every aspect of the English language.

Some General Hints

Capitalisation

Maintain a consistent style for headings, subheadings, captions, etc. Where tables, figures and sections are specifically referred to, e.g. “See Table 1.2.” then capitalise.

Acronyms

The first time an acronym is used in a document its definition should be stated (e.g. computation tree logic CTL). It is better not to introduce an acronym unless it will be used frequently or is well known.

Voice

The use of voice is debatable. Americans are beginning to write reports and papers in the first person: e.g. “I conducted an experiment.” However ’we’, ’the author’ or the simple passive form: e.g. “An experiment was conducted.” is still preferred for technical writing in New Zealand. Avoid over-use of the passive voice as it makes writing stilted and lifeless. Peter J. Denning clearly demonstrates how the passive voice lends itself to turgid writing.

Colloquialisms

Don’t use these in technical writing. E.g. “Have a go.”

That or which

That is used for a defining clause; if the clause is removed, the meaning is altered. E.g. “Dogs that eat bones keep their teeth healthy.” Which is used in a situation (usually bounded by commas) when removal of the clause is not crucial to the meaning of the sentence. E.g. “Dogs, which can be trained to do anything, love to fetch balls.”

Such as/ like

Like is used in the informal giving of examples. Such as is used in formal writing to give examples: “Languages such as Java and HUGS...”

Numbers

Numbers less than twenty should be written as words unless they are a measurement, a figure/graph/table number, or a literal value. However if there is a sentence where a small and a large number are expressed, write them both as figures. Percentages should always be written as figures. Numbers at the beginning of a sentence should be written as words (or rewrite the sentence so the number does not begin it).

For example:
“There was a 7% increase.”
“The method requires three passes.”
“The results are recorded in Table 2.”
“Twenty nine seconds elapsed.”
“There were between 4 and 32 processors in each machine.”

Useful Links

Useful sites with specific information on writing scientific reports and theses can be found at these sites:

• How to organize your thesis. Dept. of Systems and Computer Engineering, Carleton University, Ottawa, Canada
• Advice on Research and Writing for Computer Scientists (Carnegie Mellon School of Computer Science)

Useful information on general academic writing, including style, can be found at these sites:

• Guide to grammar and style, by Jack Lynch.
• A general style guide in some detail (References do not follow recommended style for COSC Dept.)

The Web Minion’s Links

• Spelling is all well and good, but it helps if you have the right word.
• If you still can’t find the word then it may be in the Merriam Webster dictionary.
• Beware of jargon.
• If you cannot afford the $20 to buy Strunk and White’s The Elements of Style then you can use the online version.