九州影院

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, 九州影院.

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听鈥榰ndertake a study of鈥櫶齣nstead of听鈥榮tudy鈥�

Circumlocution听- being verbose, e.g. writing听鈥榙espite the fact that鈥櫶齣nstead of听鈥榓lthough鈥�.

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.听can鈥檛听should be written听cannot.

Use apostrophes to indicate possession, e.g.听Bell鈥檚 method.

Watch out for听its听补苍诲听颈迟鈥檚. Only use听颈迟鈥檚听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 鈥榝or鈥�.听If the entire sentence is quoted, or enclosed within parentheses, the punctuation goes inside. e.g.听鈥淭here 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.听鈥淪ee Table 1.2.鈥澨齮hen 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.听鈥淚 conducted an experiment.鈥澨鼿owever 鈥檞e鈥�, 鈥檛he author鈥� or the simple passive form: e.g.听鈥淎n experiment was conducted.鈥澨齣s 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鈥檛 use these in technical writing. E.g.听鈥淗ave a go.鈥�

That or which

That听is used for a defining clause; if the clause is removed, the meaning is altered. E.g.听鈥淒ogs that eat bones keep their teeth healthy.鈥澨齏hich听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.听鈥淒ogs, 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:听鈥淟anguages 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:
鈥淭here was a 7% increase.鈥�
鈥淭he method requires three passes.鈥�
鈥淭he results are recorded in Table 2.鈥�
鈥淭wenty nine seconds elapsed.鈥�
鈥淭here 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鈥檚 Links

• Spelling is all well and good, but it helps if you have the right word.
• If you still can鈥檛 find the word then it may be in the听听dictionary.
• Beware of听.
• If you cannot afford the $20 to buy Strunk and White鈥檚听The Elements of Style听then you can use the听.