1. “Eschew Obfuscation”
a review of
The Craft of Scientific Writing
Michael Alley
3rd Ed., Springer, New York 1996
by
Kyle 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é
2. 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. Jensen Bioinformatics and Metabolic Engineering slide 2/10
12/12/02 Laboratory at MIT
3. 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 Electron
Avalanches in Electrical Gas Discharges
Studies on the Electrodeposition of Lead on Copper
Effects of Rhodamine-B on the Electrodeposition of
Lead on Copper
K.L. Jensen Bioinformatics and Metabolic Engineering slide 3/10
12/12/02 Laboratory at MIT
4. 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. Jensen Bioinformatics and Metabolic Engineering slide 4/10
12/12/02 Laboratory at MIT
5. Document Bodies
Narrative strategy
chronological
¡
spatial
¡
flow
¡
Sectioning
Pam Am Flight 103 Report
Debris Recovery Completed Work
Cataloguing Recovering Debris
Interpretation Cataloguing Debris
Results Interpreting the Debris
Placement Preliminary Results of Work
Bomb Makeup Placement of Bomb
Work to Be Done Construction of Bomb
Interpretation Future Work
K.L. Jensen Bioinformatics and Metabolic Engineering slide 5/10
12/12/02 Laboratory at MIT
6. Clarity in Language
Avoid needless complexity
Short words are best, and old words, when short, are best of all.
Winston Churchill
utilize use
facilitate cause “The elevated temperatures of the liquid
approximately about propellant fuel facilitated an unscheduled
implement carry out irrevocable disassembly.”
firstly, secondly,... first, second,...
hitherto until now “The higher temperatures caused the
liquid propellant to explode”
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.”
K.L. Jensen Bioinformatics and Metabolic Engineering slide 6/10
12/12/02 Laboratory at MIT
7. Punctuation
Colon
Introduces a formal list, long quotation, equation, or definition.
We studied five types of marsupials: opossums, bandicoots,
koalas, wombats, and kangaroos.
Joins two independent clauses (closely linked in
Semi-Colon
thought) or separates complex items in a list.
The reactor was cold; however, the reaction preceded as planned.
Acts as a parenthesis to separate items that can't
Dash
be separated by commas.
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.
Comma
Separates details in a sentence.
X-ray backscatter systems, which are relatively inexpensive,
require the operator’s attention.
K.L. Jensen Bioinformatics and Metabolic Engineering slide 7/10
12/12/02 Laboratory at MIT
8. Style of Language
Avoid common redundancies
already (existing) introduced (a new)
alternative (choices) mix (together)
at (the) present (time) never (before)
(completely) eliminate none (at all)
(currently) being period (of time)
Use the active voice
The voltage was displayed on the oscilloscope.
The oscilloscope displayed the voltage.
Use the first person judiciously
It was determined that... We determined that...
The authors assumed that.. We assumed that...
K.L. Jensen Bioinformatics and Metabolic Engineering slide 8/10
12/12/02 Laboratory at MIT
9. Other Readings
Graphic design
E. R. Tufte., The Visual Display of Quantitative Information.
Graphics Press, Cheshire, CT (1983)
Typesetting
L. 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. Jensen Bioinformatics and Metabolic Engineering slide 9/10
12/12/02 Laboratory at MIT
10. The End
Acknowledgements
Bill, who reads everything I write
¡
Professor Stephanopoulos
¡
Dr. Rigoutsos
¡
K.L. Jensen Bioinformatics and Metabolic Engineering slide 10
12/12/02 Laboratory at MIT /10
11. 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. Jensen Bioinformatics and Metabolic Engineering slide 11
12/12/02 Laboratory at MIT /10
12. Document Structure
Beginning Tell them what you will tell them.
title
¡
abstract
¡
introduction
¡
Body Tell them.
Conclusion Tell them what you told them.
K.L. Jensen Bioinformatics and Metabolic Engineering slide 12
12/12/02 Laboratory at MIT /10
13. 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”
¡
K.L. Jensen Bioinformatics and Metabolic Engineering slide 13
12/12/02 Laboratory at MIT /10