Tips for Effective Technical Writing

The instruction below is typical of the rules our Text Engineer writers apply every day in their writing and editorial reviews. We incorporate similar material in the corporate style guides we author. In producing a new guide for a client, we first seek information about specialized stylistic needs from management and senior staff in corporate/identity communications, marketing, and engineering. Every writer's guide - as with every writing coaching program - is crafted to serve the client's unique needs.

The purpose of the writer's guide is to impart a higher level of quality and consistency to finished documents, and enable faster review and processing. Following the guidelines we create for you will improve written communications at every level and help promote a standardized “look and feel” in customer documents. (Also see our Writing Conventions page.)

Sample topics presented include:

Technology Communications - General Authoring Principles

Formal, not Conversational English

Customer Sensitivity

Active versus Passive Voice

Avoid Pathetic Fallacy

Verb Tenses

That vs. Which and other Common Errors

 

Technology Communications - General Authoring Principles

Why do We Need Writing Standards?

• Promote most effective communication outside your organization and with customers.
• Clear, economical, focused writing holds attention.  Visually clean, mechanically sound documents minimize editorial complaints.
• Consistency and uniformity in publications builds company identity, enhancing customer recognition and appreciation.
• Be proactive rather than responsive – set and meet high document standards and prevent customer issues – put the customer first

What do Standards Govern?

• Page elements – layout, fonts, spacing, graphics.
• English mechanics – spelling, punctuation, grammar, usage.
• Organization and logic.
• Stylistic elements – word choice, writing conventions, sentence length, sentence structure, headings, lists, and  so on.

Economy and Impact in Writing

Strive to write simply and clearly. Focus on the purpose of the document and the subject of each section as you develop it.

The most effective technical writing is taut, information-rich material that easily conveys the most important points. Less is more. Although we deal with many complex concepts and brevity of expression is a real challenge, we can at least aim for crisp sentences that are free of ambiguity and
“fog.” Do not use $50 words when 50-cent ones work as well. Five-line sentences and half-page paragraphs intimidate the reader. Break paragraphs logically by discrete thoughts.

Evaluate your own drafts to identify tangential material and unnecessary descriptions that can be eliminated. The goal is sharply honed text and high-quality, relevant graphics that facilitate rapid reading and full comprehension.

Avoid wordiness and words or phrases that obscure the central meaning, for example:

Wrong:  The system is designed such that active components are capable of being tested during plant operation.

Right:  The active components can be tested during plant operation.

In summation, you should adopt a spare, direct business writing style that eliminates stilted, circuitous language. Learn the warning signs of proposalese and avoid these and similar interest-draining patterns at all times.

Formal, not Conversational English

Technical information requires more stringent standardization than is common in general usage. Colloquialisms and conversational English are inappropriate for business and technical writing.
Keep language clear and precise; formal but not pompous.

Customer Sensitivity

Condescension Harms Your Message

Do not talk down to reviewers and customers. Examples:

• It is evident that…
• It is obvious that…
• Please note that…
• Obviously…

Use Customer Terminology

Know and use customer titles for their programs. When a customer has a preferred name for an item or system that differs from the company's term but is equivalent, favor the customer’s term.

Active versus Passive Voice

Proposals and Marketing Documents

Traditionally at engineering firms, proposal managers and marketing staff have advocated assertive language and active voice to raise impact. Examples:

Passive:       After installation of the new equipment, production was doubled.

Active:         After installing the new equipment, the team doubled production.

Passive:       Several laboratory tests were conducted on the specimens.

Active:         The laboratory conducted several tests on the specimens.

Technical Documents

In technical reports, calculations and specs, it is often considered appropriate to “mask the subject”
(i.e., avoid references to I, we, the designer, or the analyst) and use passive voice. This has the effect of shifting emphasis from the performer of action (design, analysis, establishment of requirements) to the analysis results, conclusions, or requirements themselves. In other words, it gives the object in the sentence dominance over the subject.

Example 1:  The IEEE requirements must be met by all vendors.

Example 2:   From the simplified analysis model of [1], the following structural parameters were calculated for the steel supporting beams.

However, even in strictly technical documents, you can apply active voice in discussions not directly connected to the main analytical or engineering content to break the “detached” quality of passive voice and raise interest.

- Top -

Avoid Pathetic Fallacy

Steel has No Soul

“Pathetic fallacy” means the attribution of human qualities to inanimate objects. Be on guard for it, and know that lifeless components and sensors cannot see or experience anything, though they may be subjected to, or exposed to, a range of conditions.

Similarly, a management plan cannot ensure and a site cannot consider. Only we and our customers can do these things.

Possessive

A point related to pathetic fallacy is to avoid using the possessive with anything other than persons or entities.

Wrong:  The project’s baselines…

Right:  The project baselines…

 

Verb Tenses

Choosing the Right Tense

Tenses to Avoid

In technical documents, past perfect and future perfect tenses should generally be avoided.  To illustrate, you should only rarely need to use constructions like:

An analysis of the bisulfate compound had shown… (past perfect – delete “had”)

The maximum damping will have been applied in a future study.  (future perfect – change to will be used)

There are occasionally valid applications for the present participial and past perfect forms, typically in sections providing background information, for example:

The team is performing this study in conjunction with the module replacement.  (present participle)

The lab has used this testing methodology since 1995.  (past perfect)

That vs. Which and Other Common Errors

1. The word “comprise” means to include or to be made up of. A large entity cannot be comprised of smaller things. It comprises them, or is composed of them.
2. That/which – the relative pronoun that is restrictive, which means it tells you a necessary bit of information about its antecedent, e.g., The alloy that is used most often is Inconel.
   Which is non-restrictive, meaning it does not limit the word it refers to. 
   Simple rule: if you can tell which thing is being discussed without the which or that clause, use which; if you cannot, use that. If the phrase needs a comma, you probably want which.
3. Data, criteria, and spectra are all treated as plural nouns.  Other common plural forms: moduli (not modulii), formulae (preferred over formulas).
4.  Principal means main or primary; principle is a motivating idea.
5. Affect is a verb meaning “to have an influence on,” while effect is the result of being affected.
6. Basically is much overused and should be avoided in favor of such expressions as essentially or fundamentally.
7. Close proximity is a redundancy, since in proximity to means close to.
8. e.g./i.e. – When  you mean “for example,” use e.g. – an abbreviation for the Latin phrase exempli gratia.  When you mean “that is,” use i.e. – an abbreviation for the Latin phrase id est.  Both are used to clarify a preceding statement, the first by example, the second by restating the idea more clearly or expanding on it.
9. Envelop means to enfold or encompass.  Dictionary.com defines envelope as “the set of limitations within which a technological system, especially an aircraft, can perform safely and effectively.”  It is either that or what you send to the mail room, but envelope is never a verb.
10. LCD display, FEM model, etc. – LCD stands for “liquid crystal display,” so it is redundant to write LCD display.  Be careful about this in all acronym usage.
11. Refer to or see – When calling out an external document or drawing, use refer to.  When citing a graphic or document section in the current document, use see, as in see Figure 6-1 in Section 6.
12. Title/entitle – a fine point not often observed, but it is preferable to say the document is titled the Configuration Management Plan versus entitled the same.  A document is titled; an heiress is entitled.
13. Practicable; possible; practical - To quote The Chicago Manual of Style (CMS 5.202):
    
    What is practicable is capable of being done; it’s feasible.  What is possible might be capable of happening or being done, but there is some doubt.  What is practical is fit for actual use.

Additional Technical Writing Resources

Text Engineer writers and editors use all the following reference sources regularly.  You may find them quite helpful when wrestling with questions of grammar, style, meaning, or even spelling.

1. The Chicago Manual of Style.15th Edition. University of Chicago Press. 2003.  Online CMS Q&A:  http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html
2.  Style Guide for Business and Technical Communication. Third Edition. Franklin Covey Co. Salt Lake City, UT. 1999.
3. Strunk, William, and E. B. White. The Elements of Style. Fourth Edition. Allyn & Bacon Co. Needham Heights, Mass. 2000.  Online: http://www.bartleby.com/141/index.html
4. OneLook Dictionary Search:  http://www.onelook.com/
5. U.S. Nuclear Regulatory Commission Glossary:
   http://www.nrc.gov/reading-rm/basic-ref/glossary.html

(See our more exhaustive listing of writing resources.)