Bill Gardner / Frequently Committed Errors
This page is inspired by encountering a small set of recurring problems. It is divided into three categories:
Forgetting what your audience doesn't know
Before starting to write, decide what audience you're going to assume, and what technical knowledge they have. As you write, be mentally alert to things that are going to raise question marks in your readers' minds, and explain them. Avoid boring explanations of things that are common knowledge for your readers.
Referring to concepts not explained until further on in the document
Many technical subjects are full of overlapping topics that can be explained in several different orders. Because of the intertwined concepts, some "forward references" are inevitable. In such cases, your readers are NOT going to flip ahead to read the explanation, nor do you really expect them to do so. Therefore, your forward reference really means something like "please be patient, and this will be explained later."
Try to eliminate the forward reference by reordering your presentation, if it is logical to do so.
If you must keep the forward reference, then also insert some brief capsule explanation NOW so they can (1) understand enough to follow the present discussion, and (2) have a warm feeling that they haven't just been handed a meaningless buzzword.
Unsupported, brazen generalizations and claims
Avoid overclaiming that goes beyond the evidence! It is usually better to err on the side of understating your conclusions. Bad examples:
Such language is fine for newspaper/magazine articles, but not in technical writing. For every statement you make, think "Can I support this if challenged?" And if your statement is not obviously supported from the context, also state why it is true.
Well then, reconsider whether you really need to make that claim. Instead, leave it out, or find a less provocative way to state it.
Overly chatty or familiar language
Avoid "I" and "you" altogether.
Avoid contractions (like "can't" and "don't") and informal expressions (like "couple of" and "would be nice").
Limit the use of "we" and "our". They can be used sparingly, but rewording is preferred (e.g., use passive voice, call yourself "the author"). In a thesis, if the readers see we/our too much, they may think the work is not actually your own. If it truly refers to work going on in your research group, we/our are appropriate.
Abrupt shifts from topic to topic, or section to section
Insert transitional language to smooth the shift and pave the way logically, leading the reader's thinking in the right track. Follow the template: "tell them what you're going to say," "say it," "tell them what you said," and finally, "tell them where you're going next."
Careless use of passive voice
If you ever try running a "grammar check" in MS Word, you will likely find that it objects to every instance of passive voice. While this degree of allergic reaction is arguably overkill--passive voice is useful to reduce verbosity and avoid tedium--there is an important hazard to be aware of: With passive verbs, the subject is left unstated (unless you add "by..."). If done carelessly, this can result in ambiguity, which is deadly in technical writing.
Consider this sentence: "After the specification is verified, code will be generated." This leaves two questions open: Who verifies the specification, and who generates the code? Must the user do these steps manually, with the help of some tool, or are one or both performed automatically? Whenever you utilize passive voice, make sure that the subject is obvious from the context.
Irregular use of numbered headings
Start each chapter with an unnumbered paragraph that explains the purpose of the chapter and previews the contents.
Commence with numbers N.1, N.2, N.2.1, and so on, BUT do not insert headings that have no text!
If you must have a numbered heading for the purpose of organizing the sub-topics, write at least one sentence that explains what the section is about and previews the subsections' contents.
Throwing in figures and tables without explanation or numerical citation
"A picture is worth a thousand words," but they are not self-explanatory to your readers! Every figure and table should be there for some purpose, and you need words to make the purpose clear and walk the reader through the important points. Without written explanation, many of these items are virtually useless, yet they often have taken much time to produce. Don't minimize their effectiveness by carelessly introducing them.
Word processors have a way of moving figures/tables around, therefore it's risky to use language like: The table below... In the following figure... Much better to say "In Fig. 6...," etc. If your word processor can insert "below" or "above" or "on page 45" automatically, fine; but if you type it, you have to maintain it if the positioning shifts.
In terms of positioning, always put the figure/table on the same page as your introduction of it, or if it won't fit, put it on the following page. It is needlessly confusing to the reader if a table or figure appears before it is referred to, or if it comes several pages later. The ideal situation, if you know your word processor well enough, is to "anchor" the figure/table to the text that refers to it, and let the word processor put it nearby. This way, if you move the text, the figure/table will automatically move with it.
Inconsistent use of punctuation, capitalization, and abbreviations
Find out what conventions your supervisor wants to follow (or publisher demands) in these matters. Find out before you write hundreds of instances that will need to be corrected!
The "period/comma inside" rule can be a problem if you want to make clear that the punctuation is NOT a part of the characters in quotation marks. In such cases, it is better to reorder the wording so the conflict is avoided.
Missing commas
While some use (or non-use) of commas is discretionary, there are at least two situations were they are required:
In the second case, your aim is to make it easy for the reader to understand at first glance. You don't want them to have to read the sentence two or three times in order to be sure which words go together. Even if the comma is not technically required by the grammar, it inserts a "pause" for the eye that clarifies the meaning.
Missing articles
ESL writers need to be sensitive to this basic principle concerning nouns in English:
Unfortunately, when ESL writers neglect this requirement, their tendency is to write the bare singular "dictionary" form of the noun, which is almost always wrong.