BUGS in Writing, Revised Edition: A Guide to Debugging Your Prose, 2nd Edition

Description

• Copyright 1998
• Dimensions: 7-3/8" x 9-1/4"
• Edition: 2nd

• Book
• ISBN-10: 0-201-37921-X
• ISBN-13: 978-0-201-37921-1

"How often does a book come along that has you laughing out loud as it improves your writing, especially of technical and scientific material? How often does a book on writing come out aimed at scientists, mathematicians, and computer specialists in the first place? How often does a book on grammar keep you turning the pages from pleasure? Never, you say? Then get this one."

Jef Raskin
professional writer and creator of the Apple Macintosh project

"As someone responsible for the creation of numerous bugs, literary and otherwise, I heartily recommend Lyn Dupré's exquisite book: a lucid guide to squishing bugs or, even better, exterminating them before they hatch."

David C. Nagel
President, AT&T Labs

"You can borrow my dictionary or steal my thesaurus. Just stay away from my copy of BUGS."

Patrick Henry Winston
Massachusetts Institute of Technology

"The quality of scientific and technical writing would increase considerably if this book were required reading for all authors."

The Mathematica Journal

"Lyn's style is wonderful: humorous, enjoyable, and incisive. I even liked the plot."

Peter G. Neumann
author of the Dupréved Computer-Related Risks

"Those of us who have worked with Lyn Dupré treasure her keen wit, and, above all, her absolute mastery of writing."

Carver Mead
California Institute of Technology

"BUGS in Writing deserves to become a standard. If technical writing isn't your principal activity, but you find yourself doing a lot of it, you should read this book."

IEEE Micro

"This book will help me/you/we a lot/immensely."

Martin Griss
Laboratory Scientist and Reuse Rabbi, Hewlett-Packard Laboratories

"Lyn combines an intellectual command of her subject with a madcap imagination to take you on a joyous romp through the English language."

Abraham Silberschatz
Lucent Technologies

"I just received a copy of BUGS in Writing, which I think is wonderful. (Reading this sentence again, I realize it is ambiguous; but both its interpretations are true. It is also passive, but since the package was waiting for me when I returned from a trip, it is hard to know just who brought it.)...BUGS will certainly be at my fingertips during the final rewrites.

Andrew Koenig
author of C Traps and Pitfalls and coauthor of Ruminations on C++

"I highly recommend BUGS in Writing, by Dupré. It makes an excellent companion to Strunk & White and the Harbrace College Handbook."

Martin D. Carroll
coauthor of Designing and Coding Reusable C++

A "superior" alternative to Strunk and White.

Computing Reviews

"This book simply sneaks up like a cat and charms you."

Kitta Reeds
SRI International

"Having the examples weave their own story is an outstanding device. Our brains must be wired for learning from stories."

Bruce R. Montague
University of California, Santa Cruz

"Ultimately, it is the playfulness and humor of the author that encourages me to keep this book on my working shelf. I wish I'd had Lyn Dupré as my fifth-grade English teacher."

ANPA West Journal

"An earful of bugs that will learn you right from wrong."

Dick Lyon
hearing researcher, Caltech, and Senior Scientist, Foveonics, Inc.

"It's hard to describe how easy it is to read this book, except to say that it's the first style book that I have ever read entirely, and for pleasure."

Ellen Levy Finch
Expert Support, Inc.

"An indispensible 'bible' for those who believe that clarity and good writing are the key to conveying any message effectively."

Edward H. Shortliffe, MD, PhD
Professor and Associate Dean, Stanford University

"Even my cats seemed to like the book."

Denbigh Starkey
Montana State University

Like a deft and brilliant surgeon Lyn takes your mangled manuscript And dexterously cuts away Those dangling participles Those split infinitives Those fatty adjectives And returns to you An (almost) perfect body Of your work (Marred by only a few Feline paw prints). Lightning quick of mind Motion sure and filled with grace Weapon poised With sharp and blackened point She pounces! Leaps upon her prey! Death to the fractured words The split infinitive The dangling participle! The body stirs at last Returns to life Strengthened, renewed, And ready for The publisher. oTrish Hooper

020137921XB04062001



Sample Content

Downloadable Sample Chapter

Given that you are reading this page, I assume that you want to know how to write well. Given that you have that desire, I assume that you already know a considerable amount about writing. Any person who pays attention to, and thinks about, the techniques of good writing already has the necessary basis for developing ear. Ear is the ability to hear whether a given word order, sentence, or term is correct.

The simplest way to improve your expository writing substantially is to learn to avoid a limited set of extremely common errors. Because these errors are endemic in scientific literature, they sneak into the prose of even extremely bright people who write well. You probably have become so used to seeing them that you do not immediately recognize that they are problematic.

My purpose in this book is to teach you to recognize common errors instantly by describing as clearly and simply as possible what those errors are. My intention is to convey to you the basic principles of good writing, and thus to help you to develop ear, without subjecting you to the pain and boredom of absorbing the voluminous body of formal and technical knowledge on the English language. I aim to present information in a form such that you will read because the material is amusing and interesting, and in the process will learn the principles that you need to know to improve your competence in written English.

When you have a smooth, intimate relationship with written language, you have at hand a tool of enormous power: You can communicate with and convince your fellow humans.

You write a manuscript to convey information, to communicate concepts, and to persuade people. You may have numerous opportunities for writing in your work, such as the following:

• You complete a research study, and want to convey your results and conclusions to your colleagues.
• You design a software package, and want to write a manual that will tell users how it works, or to write advertising copy that will tell people why they should buy it.
• You have a hypothesis that you wish to test, and want to write a grant or contract proposal in the hope that you will obtain funding to carry out your research.
• You have been invited to contribute a chapter to a book on a topic related to your area of expertise, and want to restructure your thinking so that your theories will be accessible to people who are not familiar with your field.
• You have completed a review of work on a specific topic, and now want to write an article for a specialty journal.
• You have been asked to give a talk at a conference, and want to develop the slides for your presentation.
• You have been asked to report the progress that your department has made on a project, and want to write a memorandum or business report.

Whatever your specific reason for undertaking a writing project, when you write, your goals are to communicate and to convince.

The principles of syntax, style, and semantics structure your writing to reduce ambiguity and to add clarity. Lucid, clean writing conveys thoughts rapidly and effortlessly; murky, obfuscating prose makes readers work hard to glean any sense at all. Many of the principles boil down to common sense; implementing them reduces potential or actual confusion. Patrick Henry Winston suggests these reasons for learning to avoid common mistakes:

• Errors such as split infinitives and nonparallel fragments make reading difficult, because they place an unnecessary burden on that part of the brain that makes use of syntax. If you overload that part of the brain, there are fewer brain cells available to handle meaning.
• Errors such as word shifts -- a shovel in one paragraph becomes a spade in another -- place an unnecessary burden on that part of the brain that is trying to deal with semantics. They make your reader wonder whether the shift conveys meaning or merely reflects a misguided sense that word repetition is bad.
• Errors in general distract the careful reader, in particular a reader who writes and who cares about his writing.

I add only that errors in general detract from your credibility. Even if your reader does not herself know precisely what rules you are breaking, she will certainly notice whether your thoughts are easy to understand. If you write muddy, indecipherable prose, riddled with mistakes, your reader is bound to wonder how carefully you designed your study, collected your data, applied statistical techniques, validated your system, or otherwise behaved like a respectable scientist.

Many of the principles of syntax, style, and semantics are not strict, in the sense that experts may disagree about them. Anyone who studies language develops her own set of principles; the one presented in this book is my own, subject to my unique, opinionated biases. I have developed this set for computer people (a class that I shall identify in the next paragraph), but the principles are applicable to all technical writing; for that matter, they are applicable to any writing at all. Whether you are writing a doctoral dissertation or a love letter, your goal is to convey information to, or to convince, your reader; limpid clarity will get your point across.

I have written this book for all people who might plausibly be found wandering around in that section of a bookstore that has on the shelves computer-related books; such Homo sapiens I have dubbed computer people. You may be a computer scientist, or you may hark from any discipline that uses computers as an integral component of its work. I have explored challenges that are specific to such disciplines, such as how to set code or to style the names of the keys on a keyboard. I have also used numerous examples throughout the book to show you ways to use wisely the terminology of computers. If you are any breed of scientist, even one who does not differentiate RAM from a male sheep, you will still find this book highly applicable to your work. If you are a businessperson, you also will find in this book many techniques to help you communicate effectively and thus to work productively.

This book comprises numerous short, unordered, unlinked, easily digestible segments. That is not the usual structure for a book, and you deserve an explanation. When you begin reading, you may find the lack of hierarchy irritating. Because this book is so noticeably different from other texts whose purpose is to teach you how to write well, let us first examine the more usual approach.

Language is evolving stuff that exists in the world. We humans generally try to learn about stuff by observing it and seeking patterns that will let us classify it, and make predictions about it. Many intelligent people have observed English for ages; they have developed an immense body of knowledge, a classification system that codifies the patterns according to one model of language. The result is a huge hierarchical rule base; such rule bases are presented in style manuals.

A style manual is thus a highly organized exposition of this rule-based model, presented in a specialized terminology. Style manuals contain terms such as possessive case, appositive, restrictive function, and antecedent. Style manuals are comprehensive: They classify everything you might need to know about the rules governing the English language. I strongly urge you to purchase a good one -- my personal recommendation is The Chicago Manual of Style [Chicago: University of Chicago Press], because it is used by most publishers in the United States -- and to use it to look up answers to specific questions that arise as you write.

There is nothing wrong with that approach to modeling language; on the contrary, it is an admirable, scientific, comprehensive way of going about the business. Most editors, for example, use that rule-based system in their work. There is, however, a different way, and that way is what I will teach you in this book.

The alternative is a more intuitive, right-brain observation of language, the result of which is the development of ear. As I said earlier, ear is the ability to hear whether a given word order, sentence, or term is correct. Ear is based on numerous principles that have to do with the logic and rhythm of language. To develop ear, you learn the principles; once you have ear, you can make judgments without resorting to any specific principle. You are thus equipped to handle new, unexpected situations.

In this book, I give you a set of principles; the set is not comprehensive, but it does cover most of the problems that mistuned ears miss. I would like you to think of the segments of this book as, say, daily columns that might turn up on the opinion page of your newspaper, waiting for you at the breakfast table. Each segment covers one conceptual chunk of information, and each stands alone. You can read the segments in any order, as many at a sitting as you wish. Certain information shows up in more than one segment, for two reasons. First, because the segments are independent, I want to ensure that you do not need to refer to more than one at a time. Second, showing you how a notion applies in different situations is a good way to familiarize you with it.

I have written the book in this way, refusing steadfastly to organize it in the traditional manner, because I believe strongly that attempts to impose organization on the principles lead you to the analytic system of style manuals, rather than to the development of ear. Had I organized this book well, I would eventually have ended up with a structure identical to that of a standard style manual, and you would have in your hands a mediocre, incomplete book. I have, instead, purposely introduced chaos so that I can actively discourage you from trying to read this book linearly, memorizing the principles as you go. Instead, I want you to open the book randomly, or perhaps to find in the table of contents a segment that interests you today. No one can absorb more than a few segments at one sitting, and I do not want you to try to do the impossible. I want you to keep this book on the breakfast table, next to your hammock on the porch, on your nightstand, or wherever you will be inclined to pick it up for a bit of grazing when you have a quiet moment or two.

I want you to read around in this book, now and then, over a period during which you also do your own writing, because, as you write, you will understand more and more about how the principles apply. Every segment in this book describes a problem that many writers have; any individual writer has her own set of frequent glitches. You might want to identify your own personal subset of the principles in this book. As you read, flag those segments that describe the errors that you make most often. Then, if you learn to avoid that small set of errors, you will write smoothly and well.

Eventually, you will absorb a new model of language; you will start to understand a way of looking at language that lets you tell instantly whether the wording of a sentence sits well with you. You will develop ear, and that is my intention.

If you are teaching other people to write, this book will be a valuable tool. If you are supervising graduate students who write research reports and dissertations, for example, or are training your staff to write clear progress reports, or are helping colleagues to prepare papers for presentations, first ensure that each person has her own copy of this book. Then, help her to identify her own set of, say, her 20 most common errors. As she writes, have her check her writing for those specific problems, before she gives you the text. You will both profit from the exercise.

At the end of the book, I have included an Index by Category. You can use that index to find segments that discuss, for example, punctuation marks, or terms to be avoided. I have also included an Index of Principles. There, you will find the titles of the segments listed alphabetically, and annotated with the relevant principles. This index will allow you to relocate information when you want to refresh your memory.

No single principle is essential; once you have developed ear, you may well reject several of my ideas. If you do not yet have finely tuned ear, however, I recommend that you first simply follow the principles in this book. What sounds right to you now may well sound gratingly clumsy in the future. What sounds stilted and formal and overly correct to you now may well sound clean and pleasant in the future. Your ear will change.

Eventually, you will be able to forget the specific principles -- both the ones given here and any that you discover for yourself -- because you will have an accurate sense of the natural rhythm of language.

It is critical that you understand that the principles are derived from the language, rather than vice versa. That is, the principles are descriptive, rather than prescriptive. If you know how to apply the principles, you have competence in written English. Because the principles are descriptive, there is not always an answer to the question, "Why is the language that way?" There often is an answer, and that answer usually depends on logic and has to do with disambiguation; where the answer exists, I tell you about it. Sometimes, however, there is no apparent reason why the language behaves as it does: It just is that way.

Furthermore, in certain sections (for example, styling of numbers), I describe a set of conventions. The rationale for such conventions is that they are standards: You and other writers follow the standards to maintain consistency within and across documents.

When I write in this book

You should <follow a principle>.

I mean that, if you wish to bring your writing into line with competent written English, then you should follow the principle that I describe. I might say, for example,

You should not split infinitives.

I have used this construction because omitting you from the discussion would be unfriendly, and would leave me various unappealing options, such as simple commands (which are even more directive, in essence telling you that you must, rather than that you should) Do not split infinitives.

or passive voice

Infinitives should not be split.

or verbosity

If you wish to write well, then you might consider adopting the principle of never splitting infinitives.

or bad grammar

To write well, infinitives should remain unsplit.

Thus, I want you to understand that I am not so much telling you what to do, as I am telling you what you can do if you want to improve your writing. I needed the construction you can, however, to tell you about those situations in which there are various -- equally good -- alternatives.

Furthermore, as I mentioned, language is evolving: Language is a form of human behavior, and it is never stagnant. Be aware that the rules of spoken language are substantially different from those of written language. Be aware also that, at any given moment, a person who has competence in the language knows where to place the boundary between incorrect usage and usage that has become correct over time. The precise location of that boundary is a matter of judgment; most of the boundaries expressed in this book are reflections of my own judgment. They are here to guide you, rather than to bind you.

Because I am offering you an alternative model of language, I have avoided, to the extent practical, the terminology used to describe the rules of style and syntax. I do assume that you know, or can infer from context, the meaning of verb and noun; in general, however, I have used few such terms; when I do use them, I make sure that you and the term are properly introduced before you play together. For the most part, however, I encourage you to think of language as describing activities undertaken in possible worlds by various agents; objects or creatures can undertake activities or can be the recipients of activities.

A large portion of the pedagogy in this book is by way of example. My own experience in teaching writers has convinced me that people acquire ear by contemplating myriad examples. Two examples may seem excessive to the person who already understands the point being made, but six examples may be insufficient for the person who is trying to grasp a new pattern. If, after you read the first example, you comprehend the distinction, or structure, or other point, then by all means skip the others; they are there for other readers.

In most cases, I have given the examples in pairs or sets, showing you first the problem, and then the solution. I have not used identical sentences in the sets, for two reasons. First, reading the same sentence repetitively would bore you. Second, I want to teach you to read for structure, as well as for content. Even though the words in the example sentences are different, the structures of the sentences in a given set are identical (or are sufficiently similar that they are identical for the point under discussion).

A good writer reads a sentence in two ways: for structure and for content. If you read sentences for content only, you will be unable to discern many of the reasons for the principles, and you will be unable to apply the principles to your own writing. If you read for structure only, you will be unable to understand what a sentence means. You must read for both. Thus, I have chosen to set up the examples such that you are forced to read for both structure and content, so that you will be able to apply what you learn. Your own sentences will certainly have content different from those in the examples, but they will have the same structure. Because you will know how to read for structure, you will be able to see that your sentence is like the one on page xx of this book, and you will know how to write your sentence correctly.

Because, as I said, many principles of syntax, style, and semantics are not hard and fast rules, but rather are, to a degree, subject to opinion, I have developed the BUGS system to classify all the examples in this book. BUGS is a four-point scale, denoting

bad:	The example sentence contains a genuine error or mistake (for example, bad grammar); you should avoid the bad portion completely. Making such a mistake, embarrassment is unavoidable.
ugly:	The example sentence is technically correct, but is not acceptable for one reason or another; you should avoid the ugly portion. When one writes in an ugly manner, in order that one may sound like one knows what one is doing, one may lose credibility with the audience.
Good:	The example sentence is acceptable and correct. When you write well, you get your point across.
Splendid:	The example sentence demonstrates an improvement over a given good solution or example, or represents correct application of several points under discussion. Once you have developed ear, you will be able to tell without hesitation what constitutes correct syntax, style, and semantics; you will have competence in written English, and will be equipped to communicate effectively with your fellow humans.

Keep firmly in your mind, as you read, that the distinction between bad and ugly is one of kind, rather than one of degree. There are many bad (technically incorrect) sentences that are considerably less objectionable than are many ugly (technically correct but klutzy, horrific, stultifyingly dry, or otherwise unacceptable) sentences.

The distinction between ugly and good is, like that between bad and ugly, one of kind. It is also, necessarily, one of judgment, or of ear. That is, members of both classes are technically correct, but those in the ugly class are objectionable on a different, valuative measure. Thus, the border between ugly and good will vary across experts; the one presented in this book is mine, offered for your consideration.

In contrast, the distinction between good and splendid is one of degree, as well as one of ear. In most cases, a good sentence (one that solves the problem under discussion) is as good as it gets, so to speak; there is no splendid case. Splendid sentences are rare; they occur only when (1) there is a more graceful, more communicative, or otherwise more desirable solution, or (2) there is a solution that applies correctly more than one of the lessons in a given segment of this book.

I have classified every example so that there is no room for confusion about whether I am showing you a problem or a solution. In certain segments, I am pointing out that different word order, for example, results in different meaning; there is no bad or ugly example because all ways are correct -- you just need to be sure that what you intend to write matches what you do write. In other cases, the topic of the segment is a beast that you should generally expel from your prose, such as a redundant brutish monster beast; in those segments, the only examples are ugly ones.

I have had great fun writing this book, and I hope that you will similarly enjoy reading it. I encourage you to swim into it playfully, and to let it lap over you without worrying about what you are learning. Soon enough, you too will be entertaining yourself by writing your own manuscripts.

lyn dupré
Woodside, California
September 1994

Table of Contents

Foreword.


Read Me: Ear.


 1. Passive or Missing Agents.


 2. You and Your Reader.


 3. So, So That, Such That.


 4. Two or More.


 5. Only.


 6. Redundant Terms.


 7. Pronouns.


 8. Undefined This.


 9. Motivate.


10. Oxymorons.


11. Shall Versus Will.


12. Key Terms.


13. Proven Versus Proved.


14. Everyone, Someone, No One, None.


15. Colon.


16. Effort.


17. Which Versus That.


18. Spread-Out Phrases.


19. While.


20. Repeated Prepositions.


21. Abbreviations and Acronyms.


22. Verbize.


23. Commas.


24. Number Spelling.


25. Impact.


26. Lists.


27. Like Versus Such As.


28. Either and Both.


29. Hyphens.


30. Full Versus Incomplete Infinitives.


31. Titles.


32. Contractions.


33. Per.


34. Number Styles.


35. Quotations.


36. Fuzzy Words.


37. Parentheses.


38. Split Infinitives.


39. Is Due To.


40. Center On.


41. Quotation Marks.


42. Remarks Inserted After That.


43. Figure Captions.


44. Data.


45. Ensure, Assure, Insure.


46. Foreword Versus Forward.


47. Blocks: Theorems, Proofs, Lemmas.


48. Above and Below.


49. En Dashes.


50. As to Whether.


51. Who Versus That.


52. Though.


53. References to Parts.


54. Dates and Times of Day.


55. Reason Is Because.


56. With Terms.


57. Equals.


58. Placement of Adverbs.


59. U.S. Versus British Spelling.


60. Placement of Prepositions.


61. Different From.


62. Callouts.


63. Exclamation Point.


64. Deduce Versus Infer.


65. Citations.


66. The Fact That.


67. Cross-References.


68. Proposals.


69. Better, Best, Worst....291


70. Missing Words.


71. Aggravate.


72. Upon.


73. Whether Versus If.


74. Sections and Heads.


75. Comprise.


76. In Order To.


77. Em Dashes.


78. Eminent, Emanate, Imminent, Immanent.


79. Expected but Nonarriving Agents.


80. Its Versus It's.


81. Adverbs Versus Adjectives.


82. Persons Versus People.


83. Cap/lc.


84. Feel Versus Think.


85. Parallelism.


86. Points of Ellipsis.


87. Last.


88. Focus On.


89. Troublesome Plurals.


90. Around.


91. Nose.


92. Literal and Virtual.


93. Semicolon.


94. Code.


95. Comparatives.


96. Tables.


97. Tense.


98. Abstracts.


99. Neither Nor.


100. Will Likely Be.


101. Importantly.


102. Since.


103. References.


104. Cannot Versus Can Not.


105. Also.


106. Nonwords.


107. Missing That.


108. All Of.


109. Utilize.


110. Dissertations.


111. Issue.


112. Terms for Human-Computer Interaction.


113. So Called.


114. Note That Versus Notice That.


115. Affect Versus Effect.


116. Indices Versus Indexes.


117. Solidus.


118. Equations.


119. Half.


120. Media.


121. Not Versus Rather Than.


122. Visual Aids for Presentations.


123. Plural Abbreviations.


124. Style Sheets and Spell Checkers.


125. Maybe Versus May Be.


126. Figures.


127. Gender-Specific Words.


128. Continuous Versus Continual.


129. Fewer Versus Less.


130. Italic Type.


131. Truncated Words.


132. Percent.


133. Object, Modifier, Activity.


134. Rewords.


135. Further Versus Farther


136. Pronouns for Recipients.


137. Authorship on Research Articles.


138. Respectively.


139. Possessives.


140. Cliches, Jargon, and Euphemisms.


141. Design Elements and Eye.


142. Word Match.


143. Sex Versus Gender.


144. Awhile.


145. Footnotes.


146. Mouth.


147. Boxes.


148. Exercises, Examples, and Questions.


149. Writer's Block.


Index by Category.


Index of Principles.


Index of Photographs.


About the Author.



Updates

Submit Errata

