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!
|
i.e.
e.g.
et al
|
i.e.,
e.g.,
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).
|