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, 厙ぴ勛圖.
Topic
Technical Writing Advice
10 July 2024
HOW TO APPLY
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 Cambridge泭Australian English Style Guide, and the泭Style Book. A guide for New 厙ぴ勛圖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 厙ぴ勛圖writers and editors.泭revised and expanded by Derek Wallace and Janet Hughes is particularly useful.
Apostrophes
Expand contractions in technical writing, e.g.泭cant泭should be written泭cannot.
Use apostrophes to indicate possession, e.g.泭Bells method.
Watch out for泭its泭硃紳餃泭勳喧s. Only use泭勳喧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
Dont 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:
- 泭Dept. of Systems and Computer Engineering, Carleton University, Ottawa, Canada
- 泭for Computer Scientists (Carnegie Mellon School of Computer Science)
Useful information on general academic writing, including style, can be found at these sites:
- by Jack Lynch.
- 泭in some detail (References do not follow recommended style for COSC Dept.)
The Web Minions Links
- Spelling is all well and good, but it helps if you have the right word.
- If you still cant find the word then it may be in the泭泭dictionary.
- Beware of泭.
- If you cannot afford the $20 to buy Strunk and Whites泭The Elements of Style泭then you can use the泭.
