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, ҕl.
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. Yourstyleshould help, not hinder, the reader to understand what you are saying.
Writing Technical Documentsby Baden Eusen contains some general information on style. An excellent text for Computer Scientists isWriting for Computer Scienceby 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 CambridgeAustralian English Style Guide, and theStyle Book. A guide for New Zealand writers and editors.
Punctuation
The correct use ofpunctuationensures your work is easy to read. There are a number of very good style guides available to help you with this. TheStyle 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’tshould be writtencannot.
Use apostrophes to indicate possession, e.g.Bell’s method.
Watch out foritsԻ’s. Only use’sif you meanit is. (Its indicates possession, e.g.the dog was big, its collarwas 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 Smartby The Princeton Review contains all you ever needed to know but were afraid to ask.
Make sure the meaning of your sentence is clear. Avoidmisplaced modifiers.Subject/verb agreementis particularly important. Singular subjects take singular verbs and plural subjects take plural verbs.
English for speakers of other languages
(ESOL)
The use ofarticles, andprepositionsare two of the most difficult areas for ESOL students.Practical English Usageby 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. Denningclearly demonstrateshow the passive voice lends itself to turgid writing.
Colloquialisms
Don’t use these in technical writing. E.g.“Have a go.”
That or which
Thatis used for a defining clause; if the clause is removed, the meaning is altered. E.g.“Dogs that eat bones keep their teeth healthy.”Whichis 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
Likeis used in the informal giving of examples.Such asis 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 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 thedictionary.
- Beware of.
- If you cannot afford the $20 to buy Strunk and White’sThe Elements of Stylethen you can use the.
