12-271

Comments on Technical Writing

  1. General Comments
  2. Internal Logic
  3. Comments on Technical Writing
  4. Picky Comments about Punctuation and Foreign Phrases
  5. References
  6. Appendix A. Common Editing Marks

1. General Comments

Proofread your work. Read it out loud. Listen for awkward sentences. Listen to the flow of ideas. Does what you wrote make sense?

Organize your report. Present all the important ideas in the introduction. Expand the ideas in the body and summarize in the conclusion. For example, in the conclusion, do not recommend that ramps be installed in the gym if you have not talked about ramps in the gym anywhere else in your report.

Use headings to guide your reader. In non-technical writing, headings and sub-headings are considered unnecessary. A good writer can guide the reader without the crutch of headings. In technical writing, however, headings are essential. Each section should have a short descriptive title that tells the reader what is in the section. Using headers is particularly important when your report will have several different types of readers. Readers will look for the section of interest to them and will skip the rest of the report. If readers cannot find their section, they will not read any of the report. Remember that your readers will read the same way you do.

Write complete sentences. Every sentence needs a subject and a verb. If you are making a list (which is acceptable in technical writing, but frowned on elsewhere) be sure to give the reader a verb if it's a list of subjects or a subject if it's a list of verbs.

Do not use slang. Do not use colloquialisms unless you are an excellent writer and are sure you can get away with it.

Be accurate. Don't be wishy-washy. Avoid using words like "seems" unless it is accurate to do so. If the speaker made a conclusion, say "The speaker made a conclusion," not "The speaker seemed to make a conclusion." If the conclusion was that "the data seemed to show x," then say that "The speaker concluded that the data seemed to show x."

Use quotation marks correctly. Putting a word in quotation marks does not change its meaning. It implies to the reader that you want to use a non-standard meaning of the word -- but the quotation marks do not tell the reader what the non-standard meaning is. Do not put words in quotation marks unless you are defining them or quoting someone else.

Eliminate words that do not add meaning. If you delete words like "very," "pretty," "virtually," "literally," "actually," "simply," "quite," and "really" from your sentences, you will find that the meaning will almost always be the same.

Do not insult your readers. You can insult your readers in many ways. One way is to say that a statement is clear or obvious. If it is obvious, you should not have to make the statement itself. Another way is to assume that your readers are just like you -- and that you are normal. If you say: "Short people and normal people" this implies that you think that short people are abnormal. Another way to insult your reader is to make statements such as "The current policy is stupid." Your reader may be the person who instituted the policy. You do not have to be mealy-mouthed. If things are wrong, say they are wrong -- but give well-argued reasons.

Avoid value-laden words. If you write about the "wonderful ramps that have been installed on campus," your reader cannot tell if you are being sarcastic. Again, if you are an excellent writer, you can tell your reader (or listener) that "Brutus is an honorable man," and your reader will understand what you mean. If your goal is to communicate technical information effectively, write simply and directly.

Avoid the passive voice. Rewrite your sentences to have active verbs. Say who did what -- not what was done to whom. Try not to start sentences with weak phrases like "There are. "

Use a consistent tense. Don't jump from the past to the present to the pluperfect subjunctive tense. This does not mean every sentence has to been in the same tense, only that the main narrative should be in a consistent tense. Events that will happen in the future should be in the future tense, and events that have happened in the past should be in the past tense.

Use parallel constructions. Use the same parts of speech for words or phrases that perform the same role in a sentence or series of sentences.

This is not a parallel construction:
This system
  1. learns
  2. evaluation of alternatives
  3. to display results

This is a parallel construction:

This system
  1. learns,
  2. evaluates alternatives, and
  3. displays results.

This is not a parallel construction:

This sentence is designed to show an awkward construction and with no sense of the how the two parts of the sentence fit together.

This is a parallel construction:

This sentence is designed to show a parallel construction and to demonstrate that the two parts of the sentence perform similar roles.

2. Internal Logic

Avoid Null Anaphora (one of my favorite phrases). Do not talk about "it" unless you have told the reader what "it" is. If you use a phrase such as "these performance criteria," be sure that you have given your reader a list of performance criteria.

Define acronyms. If you use an abbreviation such as TBP, be sure you tell the reader what it means. The standard method is to use the full phrase and its abbreviation in parentheses the first time the phrase occurs and to use the abbreviation thereafter. For example, The speaker discussed Total Building Performance (TBP) ... She gave criteria for TBP ...

3. Miscellaneous English Corrections

Do not separate the verb from its subject with a comma. For example,

She ran and played. (There is no comma after "ran." No matter how long the verb phrases are, do not put a comma between them.)

She ran and she played. (A comma is optional after "ran." If the two sentences were longer, the comma would be required after "ran.")

Use "it's" and "its" correctly. "It's" is a contraction of "it is." Its is the possessive of the third person singular.

it's = it is

It's orange => It is orange

its = possessive third person singular

Its orange =>   the orange that belongs to it

One way to remember that the possessive "its" does not require an apostrophe is to remember that none of the other personal possessives such as his, hers, or theirs have an apostrophe.

Use "effect" and "affect" correctly. "Effect" and "affect" have different meanings from each other and have different meanings depending on whether you use them as nouns or verbs. "Affect" as a noun means feeling or emotion and is rarely used in everyday writing or speech. As a verb, "affect" means to influence and is a common word. "Effect" as a noun means result or consequence and is a common word. As a verb, "effect" means to cause to happen and is rarely used. While it is not strictly accurate to remember that "affect" is a verb and "effect" is a noun, it is a useful rule of thumb.

Common      

Rare        

affect (verb): To influence, produce a change
She affected the change. => She influenced the change.  
   
effect (verb): To make happen
She effected the change => She made the change happen.
effect (noun): result, consequence
Her effect was hope.=> She produced hope.
affect (noun): feeling, emotion
er affect was hope. => Her inner emotion  was hope.

Use "which" and "that" correctly. "Which" clauses give more information but could be left out without changing the meaning of the sentence. "Which" clauses are nonrestrictive.

The lawn mower, which is in the garage, needs to be fixed.
(The lawn mower needs to be fixed -- by the way, if you're looking for it, you'll find it in the garage.)

"That" clauses give necessary modifying information without which the meaning of the sentence would change. "That" clauses are restrictive.

The lawn mower that is in the garage needs to be fixed.
(There may be other lawn mowers around, but it's the one in the garage that needs to be fixed.)

People who write treaties use "which" and "that" precisely. In speech, most people use "which" almost exclusively. When you write, be aware that many "which"s should be "that"s.

4. Picky Comments about Punctuation and Foreign Phrases

Indicate paragraphs either by indentation or blank space. One or the other is necessary. Using both is unnecessary. Leaving extra space between breaks that are not paragraph breaks may confuse your reader.

If you have a quotation mark followed by a comma, the comma goes inside the quotation mark. For example:

She said, "I'll go," but I didn't believe her.

This rule applies to quotation marks followed by any punctutation, including those in bibliographic references.

Foreign phrases, and their abbreviations, usually are italicized unless they are so common that they have become part of the English language, e.g.,the "ad hoc" in "ad hoc committee" is not italicized.

i.e. stands for "id est" which means "that is" in Latin. Since both words are abbreviated, they each get a period.

et al. stands for "et alii" which means "and others" in Latin. Since just the second word is abbreviated, it's the only one that gets a period.

e.g. stands for "exampli gratia" which means "examples given" or "for example" in Latin. Since both words are abbreviated, they each get a period.

The Chicago Manual of Style states: "A comma is usually used after such expressions as that is, namely, i.e., and e.g.  The punctuation should be determined by the magnitude of the break in continuity."

5. References

The Elements of Style by Strunk and White is a good reference for help with English style questions.

The Chicago Manual of Style is good reference for the rules of English. It is less personal than the Elements of Style, but it has more rules and guidelines.

Appendix A. Common Editing Marks

On your papers, I have used the following abbreviations for common errors.

awk awkward sentence or phrase
frag sentence fragment
The sentence is missing either its subject or its verb or both.
lc Change the ltters to lower case letters
run-on run on sentence
Two or more sentences run together.
s.i. split infinitive.  Move the adverb.  e.g. replace "to quickly go"
by "to go quickly."
stet let it stand (Latin)
The original is correct; ignore the correction.
uc upper case
wc word choice
delete word
exchange letters or words