Eschew Obfuscation

The Craft of Scientific WritingMichael Alley

3rd Ed., Springer, New York 1996

a review of

byKyle Jensen

12 December 2002

Science is built up with facts as a house is with stones. But a collection of facts is no more science than a heap of stones is a house.

J. H. Poincaré

“Eschew Obfuscation”

K.L. Jensen12/12/02

Bioinformatics and Metabolic EngineeringLaboratory at MIT

slide 2/10

Motivation

� Challenger disaster of 1986

� Caused by a failure in the O-ring of rocket boosters

� Engineers knew about the problem, but failed to communicate the risk effectively

K.L. Jensen12/12/02


slide 3/10

Document Titles

� Orients the reader to your work and separates your work from others'

Effects of Humidity on the Growth of Avalanches

Effects of Humidity on the Growth of ElectronAvalanches in Electrical Gas Discharges

Studies on the Electrodeposition of Lead on Copper

Effects of Rhodamine-B on the Electrodeposition ofLead on Copper

K.L. Jensen12/12/02


slide 4/10

Document Abstracts

� Two kinds of abstracts

Descriptive This paper describes a new inertial navigation system for

mapping oil and gas wells. In this paper, we will compare the mapping accuracy and speed for this new system against the accuracy and speed for conventional systems.

Informative This paper describes a new inertial navigation system that will increase the mapping accuracy of oil wells by a factor of ten. The new system uses three-axis navigation that protects sensors from high-spin rates. The system also processes its information by Kalman filtering (a statistical sampling technique) in an on-site computer. Test results show the three-dimensional location accuracy is within 0.1 meters for every 100 meters of well depth, an accuracy ten times greater than conventional systems.

K.L. Jensen12/12/02


slide 5/10

Document Bodies

� Narrative strategy

� chronological

� spatial

� flow

� Sectioning

Debris RecoveryCataloguingInterpretationResults

PlacementBomb Makeup

Work to Be DoneInterpretation

Completed WorkRecovering DebrisCataloguing DebrisInterpreting the Debris

Preliminary Results of WorkPlacement of BombConstruction of Bomb

Future Work

Pam Am Flight 103 Report

K.L. Jensen12/12/02


slide 6/10

Clarity in Language

� Avoid needless complexity

utilizefacilitateapproximatelyimplementfirstly, secondly,...hitherto

usecauseaboutcarry outfirst, second,...until now

Short words are best, and old words, when short, are best of all.Winston Churchill

� Avoid ambiguity“Because the receiver presented the radiometer with a high flux environment, it was mounted in a steel container.”

“T cells, rather than B cells, appeared as the lymphocytes migrated to the thymus gland.”

“In low water temperatures and high toxicity levels of oil, we tested how well the microorganisms survived.”

“The elevated temperatures of the liquid propellant fuel facilitated an unscheduled irrevocable disassembly.”

“The higher temperatures caused the liquid propellant to explode”

K.L. Jensen12/12/02


slide 7/10

Punctuation

� ColonWe studied five types of marsupials: opossums, bandicoots, koalas, wombats, and kangaroos.

Introduces a formal list, long quotation, equation, or definition.

� Semi-Colon Joins two independent clauses (closely linked in thought) or separates complex items in a list.

The reactor was cold; however, the reaction preceded as planned.

� Dash Acts as a parenthesis to separate items that can't be separated by commas.

� Comma Separates details in a sentence.

Because two isotopes of hydrogen—deuterium and tritium—are lightweight, can be produced easily, and require little energy, they are prime candidates to begin the fusion process.

X-ray backscatter systems, which are relatively inexpensive, require the operator’s attention.

K.L. Jensen12/12/02


slide 8/10

Style of Language

� Avoid common redundanciesalready (existing)alternative (choices)at (the) present (time)(completely) eliminate(currently) being

introduced (a new)mix (together)never (before)none (at all)period (of time)

� Use the active voiceThe voltage was displayed on the oscilloscope.The oscilloscope displayed the voltage.

� Use the first person judiciouslyIt was determined that...The authors assumed that..

We determined that...We assumed that...

K.L. Jensen12/12/02


slide 9/10

Other Readings

� Graphic designE. R. Tufte., The Visual Display of Quantitative Information. Graphics Press, Cheshire, CT (1983)

� TypesettingL. Lamport, LaTeX: A Document Preparation System. 2nd Ed., Addison-Wesley, Reading, MA (1994)

� Mechanics (grammar)W. Strunk, E. B. White, and R. Angell, The Elements of Style. 4th Ed.Allyn & Bacon, Boston, MA (2000)

K.L. Jensen12/12/02


slide 10/10

The End

� Acknowledgements

� Bill, who reads everything I write

� Professor Stephanopoulos

� Dr. Rigoutsos

K.L. Jensen12/12/02


slide 11/10

Document Introductions

� Introductions answer four questions

� What exactly is the work?

� Why is the work important?

� What is needed to understand the work?

� How will the work be presented?

Readers should not reach the body of the document with these questions unanswered.

K.L. Jensen12/12/02


slide 12/10

Document Structure

� Beginning

� title

� abstract

� introduction

� Body

� Conclusion

Tell them what you will tell them.

Tell them.

Tell them what you told them.

K.L. Jensen12/12/02


slide 13/10

Document Endings

� Endings have two purposes

� analysis of the most important results from the document's discussion

� future perspectives on the work

� Common errors

� new evidence: “Perry Mason”

Eschew Obfuscation

Documents

Transcript of Eschew Obfuscation