Technical Writing

A Practical Guide for Engineers, Scientists, and Nontechnical Professionals, Second Edition

Phillip A. Laplante

• Éditeur: CRC Press
• Année: 2018
• ISBN:
  9780429884498
• Édition: 2
• Sujet: Technology & Engineering
• Sous-sujet: Electrical Engineering & Telecommunications

Technical Writing: A Practical Guide for Engineers, Scientists, and Nontechnical Professionals, Second Edition enables readers to write, edit, and publish materials of a technical nature, including books, articles, reports, and electronic media. Written by a renowned engineer and widely published technical author, this guide complements traditional writer's reference manuals on technical writing through presentation of first-hand examples that help readers understand practical considerations in writing and producing technical content. These examples illustrate how a publication originates as well as various challenges and solutions.

The second edition contains new material in every chapter including new topics, additional examples, insights, tips and tricks, new vignettes and more exercises. Appendices have been added for writing checklists and writing samples. The references and glossary have been updated and expanded. In addition, a focus on writing for the nontechnical persons working in the technology world and the nonnative English speaker has been incorporated. Written in an informal, conversational style, unlike traditional college writing texts, the book also contains many interesting vignettes and personal stories to add interest to otherwise stodgy lessons.

1The Nature of Technical Writing

1.1Introduction

What is technical writing? I’m afraid that there is no universally accepted definition. Many authors discuss the difficulties in defining “technical writing” and then offer their own definition. For our purposes, it is easier to define technical writing by differentiating it from all other kinds of writing. There are two main differences between technical and nontechnical writing: precision and intent.

Precision is crucial in technical writing. When you express an idea in technical writing, it may be realized in some device or process. If the idea is wrong, the device or process will also be wrong. To quote my friend, physicist and software engineer par excellence, Dr. George Hacken, “syntax is destiny.”

For example, imagine the consequences of an incorrect subscript in some chemical formulation, or a misplaced decimal point in a mathematical specification of some process for controlling a nuclear plant. Precision is particularly important in computer software. In 1962, a NASA Mariner 1 Venus satellite was lost, in part because of a misplaced hyphen in a data editing program [NASA 2017].

Precision in other kinds of writing is also important, of course. The title of Lynne Truss’ book on punctuation, Eats, Shoots & Leaves, makes this point [Truss 2004]. The title refers to the dietary habits of a panda. However, if you add a comma after the word “eats,” the title now could refer to a diner who refuses to pay his restaurant bill and shoots at the proprietor before fleeing the scene.1 But the consequences of this kind of mistake are not nearly as potentially disastrous as in the specification, design, or code of some mission-critical system. Even in legal documentation, where imprecision can have deleterious consequences, there is not the same risk of loss of a system or life.

Another characteristic difference of technical writing is that there should be no intent to evoke an emotional response from the reader. The technical writer should simply try to convey information as concisely and correctly as possible. In poetry, prose, news reporting, and even business writing, it is necessary to convey information content or a story. But in poetry and prose, it is clear that an emotional response is also desirable. The situation is the same in news, where the reporter may be looking to scare, shock, or evoke sympathy or pity from the reader. Even in everyday business correspondence such as advertising, contracts, lawsuits, job applications, and so on, a visceral response or at least a call to action is desirable. This is not the case in technical writing.

A valid objective of technical writing may include persuasion of opinions, for example, convincing readers that a commonly held view about a topic is incorrect. Conveying neutral, but correct and concise, technical information often brings about this type of education in an unemotional and nonthreatening way.

Although they may not be truly “technical”, encyclopedias, dictionaries, handbooks, directories, etc. fall under the category of technical writing. These items are truly “technical” in the sense that precision is needed.

You are likely to find equations or technical terms in technical writing—this situation is different from other kinds of writing. But equations neither define technical writing, nor necessarily do they define precision. Technical writing may exist entirely without any equations; for example, a guide may contain only step-by-step procedures for assembly, installation, use, or deconstruction of some product. Equations can also be imprecise or incorrect.

Finally, there are legal implications to technical writing. While any kind of writing can be libelous, an error in technical writing can have serious consequences. For example, writing quality in user manuals is known to have caused catastrophic software failures [Wong et al. 2017]. Other technical writing errors could lead to financial loss, damage to property, environmental catastrophe, injury, or death. Consider, for example, the potential consequences of the following: bad financial advice in an investment brochure, a wiring instruction error in a manual for an electric clothes dryer, an error in a hospital record for a seriously ill patient, an incorrect formulation recipe for mixing pesticides, or an error in the maintenance instructions for an aircraft.

1.2Who Writes Technical Documentation?

I imagine that if you made a list of professionals who must write technically, you would include engineers, scientists, architects, physicians, lab technicians, and so forth. In the broadest sense, virtually any trade or profession can be considered to have a technical component, and its practitioners must prepare technical writings. Think about doctors, nurses, farmers, lawyers, and experts of all types. Every one of these persons will write in the jargon of their discipline—a kind of technical writing. From this point forward, when I say “technical professional,” I mean a large and flexible collection of any profession or trade where technical writing can occur.

Everyone is a technical writer, at least occasionally. Product complaint letters, driving directions, or recipes written for friends are all kinds of technical writing. Disclosures to insurance companies, responses to legal inquiries, and incident reports at work should also be treated as technical writing—in these it is especially important to be very precise, include provable facts, and avoid expressing emotion. Whenever you endeavor to write something at work or elsewhere, pause to consider if that writing should be treated as technical.

1.3Taxonomy of Technical Writing

For ease of discussion throughout the remainder of this book, I refer to the taxonomy described by Montgomery and Plung [1988], shown in Figure 1.1.

Figure 1.1An illustrated taxonomy of technical writing. (Redrawn from Montgomery, T. and Plung, D., Proc. of International Professional Communication Conference, 1988, Seattle, Washington, October 5–7, 1988, pp. 141–146.)

Pedagogically oriented technical writing focuses on teaching, for example, a calculus textbook or a book for the novice photographer. Technical writing of a theoretical orientation involves various kinds of theoretical and applied research. The broadest form of technical writing—professional orientation—serves the needs of various professionals. As has been mentioned, these professionals may be in any discipline. Professional orientation is the class of technical writing on which I will concentrate.

Although briefly mentioned by Montgomery and Plung, at the time their paper was written, electronic media was very new. Since then, however, a new form of written media and a unique style of writing have emerged. I would like to expand Figure 1.1 to include these forms of professional writing, adding a new category under “Professional Orientation” called “Electronic Media” (see Figure 1.2).

Figure 1.2An updated vers...