Tips for Technical Writing

Technical writing -- writing papers, reports, proposals, theses, etc. -- can be hard. Doubtless, content is important, but content is not all. A bad presentation often is glaring and can be to the detriment of the paper irrespective of content. On the other hand, good presentation often results in praise for the content -- misplaced credit sometimes.

Good technical writing conveys information or ideas clearly and concisely. Superfluity is a symptom of ill-developed conception, while vagueness undermines the ability of the writer to communicate with the reader. The following list is meant to be used as a checklist for any technical material you write.

Grammatical Errors and Bad Usage Wrong Right
Split Infinitives
It's grammatically incorrect to split an infinitive.
to quickly calculate
to calculate quickly
Split Compound Verbs
An example of poor usage that is common is to split compound verbs with adverbs.
may sometimes be called
is frequently updated
sometimes may be called
is updated frequently
Misplaced Apostrophes
Only when two words are written as one, do you need an apostrophe to account for missing letters.
In technical writing, it is considered bad usage to compress words using apostrophes.
Its a hard problem.
The dog bit it's master.
I did'nt stop.
It's (It is) a hard problem.
The dog bit its master.
I didn't stop.
Improper Possessive Proper Nouns
Pluralised common nouns must not have an 's' to denote the possessive case. Proper nouns require the 's'.
Davis' theory
the tanks's positions
Davis's theory
the tanks' positions
Missing Hyphens
Compound words (typically, adjectives) require hyphenation.
The problem is ill understood.
geographically distributed resources
The problem is ill-understood.
geographically-distributed resources
Misplaced Prepositions
It is incorrect to end a sentence with a preposition. Avoid inserting unnecessary prepositions.
I know where he is at.
I know where he is from.
I know where he is going to.
I know whom he is going with.
I will meet with you.
The lawn is outside of the house.
I know where he is.
I know from where he is.
I know where he is going.
I know with whom he is going.
I will meet you.
I will meet him with you.
The lawn is outside the house.
The paint is on the outside of the house.
Restrictive vs. Non-Restrictive Clauses
When an adjective clause restricts the scope of its noun, use "that", else use "which". Usually, "which" clauses are enclosed between commas.
Code that is written in a programming language is buggy.
Programs which are correct get full grade.
Code, which is written in a programming language, is buggy.
Programs that are correct get full grade.
Misplaced Punctuation
Be careful where you put your commas and periods!
et al
et al.
First-class Citations
When citing a reference, do not refer to it directly as if it were a part of speech.
An alternative approach is in [13].
Alternative approaches exist [13].
Smith et al. present an alternative approach [13].
Unhelpful Citations
If the conference or journal does not forbid it, make the citation more informative by including some or all of the authors' names and a year.
Alternative approaches exist [13].
Alternative approaches exist [Smi96].
Alternative approaches exist (Smith et al. 1996).

Anand Natrajan, anand@anandnatrajan•com, Writing Tips