Principles of Effective Technical Writing

Abstract

In response to the crucial importance and unfortunate absence of good technical communication in science and industry, general principles of effective technical writing are outlined and illustrated.

Introduction

It is clear that our present culture is becoming increasingly technological, specialized, and information-dependent. These dramatic changes are making the need for effective technical communication more critical and evident, for such communication is the lifeblood of science and industry, as well as government and academia. "People in technical fields need to express their ideas clearly. Engineers spend 50 to 70 percent of their time communicating; their supervisors, even more; technicians, scientists, and other technologists, often as much." ([3]; xi). This need is exemplified by the great importance of research papers, proposals, engineering reports, computer documentation, etc. These examples are all of the primary form of technical communication — technical writing — which is the interdisciplinary realm of technical communication.

In contrast, the significance of good technical writing has not been matched by a devotion to it among scientists and scholars: "Yet the President's Science Advisory Committee felt it necessary to express its concern: 'That so many American scientists and technologists can neither write nor speak effective English; that the new language of science and technology is turgid, heavy, and unclear.'" ([3]; xi)

The quotation above provides good evidence that poor writing pervades government as well, illustrated by the fact that the Committee's statement is grammatically incorrect.

As a result of this inability to communicate clearly, progress in fields of science and technology is hindered. Moreover, the prevalence of ineffective technical writing exists mainly because writers are ignorant of the significance and fundamentals of good technical writing.

Principles

I shall first consider the content of the technical manuscript, and then the structure. One important aspect of technical writing is the preliminary research. In essence, one must fully understand the material that is to be communicated. In other words, one must understand the concepts and their particular applications well enough to explain them adequately to others. (This fact may seem obvious, but it is often ignored.) Furthermore, one's grasp of the ideas should be solidified through practical experience in applying those ideas, thereby adding depth and confidence to that knowledge. For instance, a documentation writer should become quite familiar with the particular computer system before writing any sort of system manual for it.

Careful planning of the work before beginning it pays off handsomely both during and after the writing process. This is illustrated in the field of engineering: "The best way to write an engineering manuscript is to build quality into it from the bottom up — in the planning — rather than to try to inject quality into it from the top down, after the paper is finished." ([5]; 2).

Clearly, before any writing of the manuscript is begun, its thesis (i.e., exactly what is to be communicated) must be explicitly identified. The thesis should be directly determined by the purpose of the work. For instance, if the purpose of a particular report is to communicate some specific and brief information, then the thesis of the report is precisely that specific material. In turn, the report should consist only of that specific information, stated completely and concisely, and not buried in pages of pointless material thrown in to make the report seem more substantial than it is, as is often done.

After determining what is to be presented, one must decide upon the optimal structure and style of presentation. This is followed by an outline of the manuscript, which is important primarily because it sets the tone for the entire writing project, and it is at this stage that decisions about the structure of one's material are paramount. From this outline one produces the first draft. After a sufficient 'cooling-off' period (during which one does not work on the material), the first draft should be revised with as much critical honesty as one can muster. This process should be repeated until one is completely satisfied with the final product.

The most important aspect of technical writing is the content of the work. Of course, the manuscript should be complete, that is, it must contain all of the material that you wish to communicate. Incompleteness to any significant extent causes not only inadequacy in the material but possible discontinuity as well. Jean Dieudonné reiterates this from a mathematical perspective: "For textbooks,… all the details must be filled in with only the exception of the completely trivial ones. In my opinion, a textbook where a lot of proofs are 'left to the reader' or relegated to exercises, is entirely useless for a beginner." ([6]; 63)

On the other hand, the written work should not contain any superfluous material. In the process of revising the manuscript, one must eliminate all irrelevant or duplicated material, from simple syntactic redundancies to entire sections that could be replaced with a reference to a different work. Any text that should be included yet doesn't bear directly on the main topics can be put in the appendices. Although repetition is sometimes valuable (e.g., in a lecture) and is inherent in much written work (because of introductory and concluding sections), if a point is stated clearly once in the appropriate location in the text, then it need not be repeated.

One common form of superfluous material is simple wordiness. Brogan reminds us to "Use the simplest words adequate to carry your message. Long and weighty ones are not signs of literary skill; they often signify just the opposite." ([3]; 83). This principle is ignored in the following example: "Does the set of all translations form a group? The answer is in the affirmative…" ([4]; 21). Instead, the author could have written, 'The answer is yes', or better, 'The set of all translations is a group'. In general, be concise: brevity is still the soul of wit.

Another necessary characteristic of one's technical writing is consistency. The material must be internally consistent, that is, no one part of the text should directly or indirectly contradict any other part. Moreover, it should be externally consistent, i.e., no part of one's manuscript should contradict any outside material that is demonstrably valid.

A key to all excellent writing is proper grammar. One should always seek the word that most precisely and simply represents the particular idea, not the word that sounds the most erudite. Long and heavy words burden the sentence with semantic noise and bore the reader. Rather, choose descriptive and straightforward nouns. Also, stick to active verbs, as suggested by Brogan: "Verbs are sentence muscle-action words. For vigorous prose they have to be free — giving direct, immediate impact." ([3]; 35).

Having chosen the best words, form the sentence so that it communicates the idea efficiently and clearly. The following example illustrates how not to do it: "But the more one tries to pin down what a relation is in the abstract, the more it slips out from under." ([4]; 49). The author could have instead written, 'It is not easy to define an abstract relation'. Also, the length of the sentence is irrelevant if its meaning is well expressed.

Uniformity of presentation is another characteristic of good technical writing. Although a diversity of perspective in non-technical writing can be valuable, a technical manuscript should present only one interpretation of the facts. If a number of authors are contributing essays to a work, then their positions must be consistent, else the reader will be confused by conflicting information. Furthermore, uniformity in writing style is to be preferred, especially if a work is being revised by an author other than the original one.

Correct emphasis is often neglected by technical writers, thereby forcing the reader to plow through the entire text just to find the major points. Naturally, one should strive to emphasize the most important information in order to distinguish it from secondary details. The primary points can be stressed through structure as well as semantic indicators.

In terms of writing style, each author will bring to his or her work a unique style, very much a result of his or her writing goals and experience. There are conflicting views as to whether the style of presentation should be personal (such as in the writing of Paul Halmos, [6]), or impersonal (the current style in most textbooks). Actually, one's writing style should be determined by the subject matter and its intended audience. For instance, a reference book should be terse and impersonal, because the reader wants facts quickly; but an introductory textbook should be personal and enthusiastic, so as to enhance readability.

A manuscript may have superb content and satisfy all of the above criteria, and yet still be a disaster due to poor structuring of the material. There are four major reasons for properly formatting the material: (1) The topics and specific information that the reader is looking for are more easily located. (2) A correct format conveys the structure of the ideas and their relations to one another. (3) Correctly formatted manuscripts are much easier to read and understand. (4) Alterations in the material (rearrangement, addition, and deletion) can be more easily accomplished.

The three best structures are top-down (general to particular), bottom-up (particular to general), and linear (e.g., chronological). Although selection of an effective structure for one's manuscript is important, consistent adherence to the chosen structure is more important.

Excellent figures and tables can often replace text, as well as highlight the visual aspects of the information. For example, the graph of a complicated function gives one a better idea of its behavior than does its defining equation. The same principles outlined above for the content and structure of the text apply equally to all figures and tables. In addition, it is crucial that the illustrations be uncluttered.

Examples

The dichotomy between good and bad technical writing is well exemplified in a brief comparison of two introductory textbooks, both titled Ordinary Differential Equations; one is by Garrett Birkhoff and Gian-Carlo Rota, the other by Vladimir Arnold. I begin this comparison with the prefaces of both books. Birkhoff and Rota begin their book by writing that "The theory of differential equations is distinguished for the wealth of its ideas and methods. Although this richness makes the subject attractive as a field of research, it has frequently left the student confused. For many students the transition from the elementary theory of differential equations to the study of advanced methods is too abrupt. One of the chief aims of the present text is to make this transition smoother." ([2]; v)

The above passage is characterized by brevity and readability. Birkhoff and Rota continue: "We have tried to present a balanced account of the most important key ideas of the subject in their simplest context, often that of second-order equations." ([2]; v). Within this statement are embodied (both in use and in intended presentation of material) many characteristics of quality technical writing: balance, proper emphasis, and simplicity. In contrast to the clarity and straightforward manner of the above quotations, Arnold begins his book with the following: "In selecting the subject matter of this book, I have attempted to confine myself to the irreducible minimum of absolutely essential material. The course is dominated by two central ideas and their ramifications: The theorem on rectifiability of a vector field (equivalent to the usual theorems on existence, uniqueness, and differentiability of solutions) and the theory of one-parameter groups of linear transformations (i.e., the theory of linear autonomous systems)." ([1]; vii)

As the first few sentences of the book, the above are too dense, dry, and uninviting.

Another significant aspect of textbooks is the material that the reader is assumed to know beforehand. Birkhoff and Rota explicitly state what that is: "Our exposition presupposes primarily the calculus and some experience with the formal manipulation of elementary differential equations. Beyond this requirement, only an acquaintance with vectors, matrices, and elementary complex functions is assumed throughout most of the book." ([2]; v)

Any other material that the reader of their book may not be familiar with is explained within the text or in the appendices. For example, Appendix B deals with numerical integration in the programming language BASIC, and begins with a concise summary of that language.

In his introductory textbook, on the other hand, Arnold presupposes more than just calculus, namely "…elementary courses on analysis and linear algebra." ([1]; vii). Unfortunately, the reader soon finds that prior courses in advanced analysis and elementary differential equations are essential.

It is clear to the reader of Birkhoff and Rota's textbook that the authors are concerned with the readability of their work: "…the introductory chapters and those dealing with numerical algorithms have been carefully reorganized for greater readability." ([2]; v). This concern is shared by the publishers, John Wiley and Sons, who chose an excellent type as well as format for the book.

I now consider the introductions of both textbooks. Birkhoff and Rota begin by explaining that "A differential equation is an equation between specified derivatives of an unknown function, its values, and known quantities and functions. Many physical laws are most simply and naturally formulated as differential equations (or DE's, as we will write for short)." ([2]; 1)

Their introduction defines and illustrates various differential equations, solutions, degrees, and graphs of solutions in a clear manner. They then review the Fundamental Theorem of Calculus, and continue with first-order linear differential equations.

Arnold begins his introduction as follows: "The theory of ordinary differential equations is one of the basic tools of mathematical science. The theory allows us to study all kinds of evolutionary processes with the properties of determinacy, finite-dimensionality, and differentiability." ([1]; 1)

He then launches into phase spaces, phase flows, t-advance mapping, one-parameter groups of transformations, extended phase spaces, integral curves, differentiable manifolds, and diffeomorphisms, all crammed into six pages. His introductory textbook is anything but introductory.

This brief comparison of these two textbooks illustrates some of the important aspects of textbook writing (and all other forms of technical writing) that should be borne in mind by the author(s): brevity, readability, balance, proper emphasis, reasonable presuppositions, and the appropriate level of difficulty of the material.

Conclusion

The principles of effective technical writing presented in this paper are useful only to the extent that individual writers utilize them. Apply them consistently and vigorously to all your writing, including technical, and you will develop powerful skills in written communication.

Poor technical writing has been likened to bad weather: people complain but can't do anything about it. Yet unlike the weather, technical writing is produced — and can thus be improved — by those working in the technical fields.

References

1. Arnold, Vladimir I. Ordinary Differential Equations. The MIT Press, 1973.
2. Birkhoff, Garrett and Gian-Carlo Rota. Ordinary Differential Equations. 3rd ed. John Wiley and Sons, 1978.
3. Brogan, John A. Clear Technical Writing. McGraw-Hill Book Company, 1973.
4. Jones, Burton W. An Introduction to Modern Algebra. Macmillan Publishing Co., 1975.
5. Michaelson, Herbert B. How to Write and Publish Engineering Papers and Reports. ISI Press, 1982.
6. Steenrod, Norman E., Paul R. Halmos, et al. How to Write Mathematics. American Mathematical Society, 1973.