Effective Technical Writing in the Information Age

Special Stylistic Issues in Technical Writing

PrintPrint

To become an effective technical stylist, you must understand some of the key governing conventions. A few stylistic issues emerge as worthy of special attention here, especially since professors can be particularly sensitive to them. See the lessons in this section not as binding restrictions on your style, but as opportunities to understand (and in some cases, debunk) some oft-repeated rules of professional communication. In technical writing, as in chess, it is prudent to wield your creativity only within the rules.

Eliminating Contractions

Contractions—in which an apostrophe is used to "contract" two words into one by joining parts of them—are considered to be informal, conversational expression. In the formal writing that you do for your classes, or as you submit formal work for an editor’s or superior’s perusal, you simply do not have the option of using contractions unless you are quoting something that contains contractions. If you use contractions in formal writing you may appear sloppy and unprofessional. The safest idea is to avoid them entirely. If you avoid contractions, you will discover that your writing becomes more emphatic and leans toward the active voice, so the benefits are multiple. Remember: in technical writing, apostrophes contracting two words (e.g., "it’s," "they’ve," "who’s") signal that the two words can and should be written out separately.

Curbing Feelings and Personification

Of course scientists and engineers have feelings, but use of the word "feelings" or the verb "feel" in technical writing often leads the writer into trouble. Phrases such as "I feel that the best answer is 3.2" or "we feel that this conclusion is correct" can draw large frowns from your readers. "Feel" has emotional connotations, and feelings are not a relevant part of rational conclusions in your writing, at least not on the page. Also, the needless use of the term can lend the appearance of uncertainty, especially when applied to quantities or conclusions as it is above.

A related issue is the use of unintentional personification—i.e., assigning human traits to inanimate objects—in technical writing. In a phrase such as "when the drillstring feels the weight," the seemingly literal claim that an inanimate object such as a drillstring "feels" anything is clearly inaccurate. Similarly, a sentence such as "Boeing stock enjoyed a 2% increase today" could imply that stocks have emotions. Although such a sentence may well appear in the daily newspaper, its tone would not suit a technical paper. In technical writing, avoid unintentional personification, which is always revealed by the verb you use to express a noun’s action.

Choosing Gender-Neutral Language

From a stylistic standpoint, one of the best things about the need for writers to choose gender-neutral language is that it forces them to explore the options that have always been available to them. Most students are aware that they should choose gender-neutral language when they write and give oral presentations, but if it just causes them to use "his/her" repeatedly then they are not living up to their obligations to keep their writing highly readable and efficient. Also, writing a sentence such as "Someone should lend their voice to this problem" is still grammatically unacceptable because "someone" is singular and "their" is plural. Most good writers attack the problem in the following ways:

  • By simply being more specific or creative about word choice (writing "humans" rather than "man").
  • By using plural nouns rather than singular ones when appropriate ("scientists" rather than "a scientist"), or by avoiding gender-specific pronouns ("the author" rather than "he").
  • By writing "he or she" (not "he/she") when it is not awkward or overly repetitive to do so.
  • By changing some words to other parts of speech, thereby avoiding gender-specific pronouns ("walking" might work better than "he walked" as long as the grammar of the revision is sound).
  • By alternating between using "he" and "she" (as I have done in this handbook), especially in longer pieces.

With these tactics in mind, consider the following example:

The consumer himself has the power to reduce fuel costs: If he sets his residential thermostat 2 degrees higher in the summer and 2 degrees lower in the winter, he saves energy.

In a revised version of this sentence, the gender-specific language of the original is avoided:

Consumers have the power to reduce fuel costs: By setting their residential thermostats 2 degrees higher in the summer and 2 degrees lower in the winter, they save energy.

Standard English usage still calls for the masculine form ("he" or "his") to refer correctly to either gender in writing, but rely on this only when you have to. In technical writing, do not let your concern for gender-neutral language cause your usage to be too unconventional ("personhole cover"? "personkind"? "s/he"?); instead, do exercise your options as a writer wisely, and remember that our language is always in flux. Keep your eye on it.

Keeping Jargon in its Place

Jargon, especially that which has grown out of computer usage, genuinely enriches our language, so I do not want to give it a bad rap. (Why not delight, for example, in jargon such as "debug," "flame," and "FUBAR"?) However, many professors and employers criticize the use of jargon (sometimes called "buzzwords" or "gobbledygook"), especially in formal writing, so you must understand how to recognize it and when it is unacceptable.

The forms of jargon range from redundancy ("red in color"), overly formal wordiness (using "at this point in time" rather than "currently"), and specialized technical slang (using "airplane rule" to describe the concept that greater complexity increases the likelihood of failure). Clearly, when jargon takes the form of redundancy and wordiness, simple editing is critical; when jargon becomes specialized slang, we must consider audience and context to decide on how much jargon is appropriate. A hip group of hackers might know that "angry fruit salad" refers to visual design that includes too many colors, but a general, educated audience would not.

When discerning whether to use jargon, employ the following principles:

  • When tempted toward a wordy construction or fancy word, elect the simpler wording or word (e.g., "today" rather than "in today’s modern society"; "sandy" rather than "arenaceous").
  • When you feel jargon is necessary in speaking or writing but your audience members might not understand it, explicitly define the terms you use (as I did in the previous paragraph), or define terms by creating context for them in the sentence.
  • Use technical slang, but do not overuse it, in presentations, in conversation with peers, in interviews, in e-mails and memos, and in cover letters, but only when your audience is certain to understand your meaning.

Self-Study

Professional and government organizations are just as concerned about overuse of jargon as your professors are.  Check out these sites for tips and an action plan to reduce jargon and communicate more clearly:

"Jargon in Technical Writing" article from the Weed Science Society of America

"National Action Plan to Improve Health Literacy," from the U.S. Department of Health and Human Services

Destroying Dangling Modifiers

Dangling modifiers are a common occurrence in technical writing and are easily overlooked by the writer, who assumes the reader will automatically follow the sentence’s meaning. Especially when you use passive voice, it is easy to create dangling modifiers—that is, descriptive words that seem to "dangle off by themselves" because they do not accurately describe the words next to them. Most often, writers dangle modifiers at a sentence’s beginning. Grammatically, a group of words preceding a sentence’s main subject should directly describe the subject; otherwise, that group of words can become a dangling modifier. The following sentences contain dangling modifiers:

Using an otoscope, her ears were examined for damage.

Determining the initial estimates, results from previous tests were used.

Even though these sentences are understandable, grammatically they are unacceptable, because the first implies that the ears used the otoscope, while the second implies that the results themselves determined the initial estimates. The words that describe a sentence subject must be sensibly related to the subject, and in these two sentences that is not the case. Although here the intended meaning can be discerned with some minimal work, readers often have a hard time sorting out meaning when modifiers are dangled, especially as sentences grow longer.

Revisions of these sentences to avoid dangling modifiers involve changing wording slightly and shuffling sentence parts around so that the meaning is more logical:

Her ears were examined for damage with an otoscope.

Results from previous tests were used to determine the initial estimates.

Particularly when you are writing the "Experimental" section of a technical report, or anytime when you must use the passive voice regularly, take special care to watch out for dangling modifiers. The more frequently dangling modifiers are used, the more likely a sentence’s meaning can become obtuse. The result is sentences that may be both unclear and inelegant.

Self-Study

Further reading on dangling modifiers is available from these two university sites:

Exercise on modifier placement from Capital Community College

"Avoiding Misplaced and Dangling Modifiers" article from Towson University

Using "I" and "We"—the First Person

A few years ago, an old dog taught me a new trick. I edited a technical report for a gentleman who works for a government agency and has authored over 200 papers. He was highly respectful of all my editorial suggestions, but corrected me on one. I told him that he was bucking convention by using "we" throughout his report, and that the standard was to avoid using the term in technical writing, just as I had been told by others. He assured me that he had "breezily been getting away with it" for 40 years, and I agreed just as breezily that he should not change his practice after such a winning record. Finally, I came away from our interaction with an important question: Was this scientist-author a maverick, or was he in fact practicing the customary?

To form an answer, I pulled 40 journals at random from one of my university’s technical library’s shelves. The journals ranged from the international refereed European Journal of Mineralogy to the more advertising-driven Spray Technology and Marketing. To my surprise, in 32 out of the 40 journals, the authors indeed made liberal use of "I" and "we" (referred to grammatically as "the first person"). In one case (an article in Water Resources Journal), the authors used "we" in nearly every paragraph. I realized then that I had been upholding a principle that was either outmoded or at least in flux, without considering the convention in the published literature. A lesson learned.

Nevertheless, addressing the issue here is not as simple as saying "go ahead and use the first person freely." Here are some considered guidelines to follow:

  • You can use the first person in an abstract or introduction to stress the foundations of your particular approach, express authorial intentions, or emphasize your scientific convictions:

    In this paper, I argue that . . .

    In contrast to other authors, we conclude that . . .

  • When the first person does not suit you or your reader’s taste, but you need to be self-referential, consider the common alternatives such as "this author," "this paper." Keep in mind, though, that these options can sound a bit stilted.
  • In memos, especially when they involve one-on-one communication between you and one other party, use the first person (and the word "you") as needed, in particular in the introduction and conclusion.
  • Use the first person plural ("we") when you wish to include the reader as part of a collective, thinking body:

    We can agree that something must be done about the quality of care in HMO programs.
  • Limit your use of the first person so that you do not create circumstances requiring you to use it repeatedly. For example, by convention, avoid using the first person in the "Experimental" section of a technical report—if you begin to use "we" in this section, you would continually have to repeat its use for consistency.
  • Be particularly cautious with first-person terms suggesting ownership—e.g., "my" and "our." It would be awkward to write "I connected my patchcord" or "We closed our tank," in that the issue of ownership is irrelevant to the science and interpretation.
  • By convention, you may use the first person plural ("we") to introduce equations:

    We can calculate the green densities of the pellets with the equation . . .

Despite what I have outlined above, recognize that some professors and editors will adamantly reject the use of first person pronouns in technical writing. Revise accordingly when needed.

Using "This," "It," and Other Pronouns

Do you want to annoy and confuse your readers? Then paste a paragraph together with "this" or "it" as a connecting word in nearly every sentence. Moreover, do not refer to anything specific with the "this" or "it"—keep the meaning vague. (For the highly literal among you, please note that I have just employed mild sarcasm.) Without realizing it, many writers habitually plant a "this" or "it" wherever they sense that flow is needed. However, they often create confusion by doing so. Most of the time when you use "this" or "it" you are actually referring to a specific noun or verb that is nearby, or to an idea that has just been implied if not explicitly stated. To avoid confusion, one sound practice is to name whatever the "this" refers to immediately after it (i.e., "this phenomenon," "this principle," "this variation"). Note how much clearer the following sentences are because "this assumption" is used rather than just "this" by itself:

The burial by thrusting is believed to occur rapidly. This assumption, however, is difficult to test.

Here, "this assumption" clarifies that a belief is being described rather than the burial by thrusting or its rapid occurrence.

Commonly, "it is" is overused as a sentence beginning. "It is this water that could become . . ." is better written as "This water could become . . . ." When the use of "it" is vague or unnecessary, try to simply eliminate the word.

The same principle described above applies to pronouns such as "that" and "these": Do not overuse them, and when you do be sure that the reader can easily discern the words or ideas being referred to.

Because I decided against making this manual too much of a grammar text, I have only scratched the surface here on the subject of effective pronoun usage (e.g., I have not even touched on the dreaded "who" and "whom" distinction). If you find that you consistently have trouble with pronouns, I recommend further study.

Writing with Infinitives—to Split or not to Split?

A split infinitive is a phrase in which one or more words are placed between the word "to" and its accompanying verb. "To boldly go" is a split infinitive (a famous one, in fact, even to non-Trekkies) because "boldly" is interrupting the more basic pattern "to go." Split infinitives are pet peeves of many professors (and grammar checkers too), so you must consider how you will handle this issue. Read on:

The grammatical thorn that emerges when infinitives are split essentially has to do with the concept of unit interruption. Our ears (and the "rules" of our language) prefer that certain units not be interrupted. For instance, for many writers, "have worked diligently" is more acceptable than "have diligently worked," in that the verb "have worked" is not interrupted in the first instance. (Also, work in itself cannot be "diligent," per se, and the phrasing "have diligently worked" could imply otherwise.) To dramatize the point further, consider the serious, especially irksome unit interruption that occurs in an incorrect phrase we have all heard: "a whole nother."

Now consider this sentence, which contains a split infinitive:

The plastic contains a catalyst that causes it to completely and naturally disappear in a few months.

In this sentence, some readers would insist that "to" and "disappear" are too far away from each other, in that their grammatical purpose here is to serve as one uninterrupted unit. A revised version of the sentence would bring together the two words in question, thus:

The plastic contains a catalyst that causes it to disappear completely and naturally in a few months.

Now, "completely and naturally" is more obviously describing the intact phrase, "to disappear." As in this case, usually the words that split an infinitive can go outside the infinitive or be omitted altogether.

Nevertheless, split infinitives do appear in writing, and many writers (including me) find them acceptable as long as they are infrequent and that they do not disturb either sense or sound. At times, in fact, split infinitives are the most logical, euphonious choice:

After the mishap, he was encouraged to never report to work again.

It is comforting to finally understand differential equations.

The bottom line: If you split infinitives, do so infrequently, and understand that some of your professors might view them as unacceptable or sloppy style.

Ending Sentences with Prepositions

Prepositions—small connecting words such as at, about, to, under—are used to clarify relationships between other words, especially between verbs and the receivers of the verb’s action. We have all heard admonishments against ending sentences with prepositions, but such a rule never really existed—as with the principle of not splitting infinitives, it was mostly passed down by grammarians who were attempting to make written English conform to the rules of Latin. Even the purist grammar handbook that I began using in the 1980s, Martha Kolln’s Language and Composition, calls the notion that sentences may not end with prepositions an "absurd warning."

Of course, as a matter of style, ending a sentence with a preposition can give undue stress to the preposition, leaving the reader with the feeling that the sentence has ended weakly (e.g., "He wasn’t sure which sample to look at."). Therefore, if a sentence ending with a proposition sounds weak to you, revise it by moving or eliminating the preposition, but do not defy meaning or the natural word order.

And for those who would argue with you over this issue and insist on the "rule," point out to them that it is sometimes just darned inconvenient and illogical not to end a perfectly understandable and strong sentence with a preposition. You can even cite two authorities on language: William and Winston. Shakespeare’s Henry V includes the line, "Who servest thou under?" And the always quotable Winston Churchill, to demonstrate the inconvenience when the so-called rule is followed, is reported to have put his feelings on the matter thus:

This is the sort of English up with which I will not put.

So there. Smile