Transcript F6 project analysis

Technical writing
part two
Richard Golding
IBM Almaden Research Center
www.chrysaetos.org/papers/Writing-2-2007-11-6.ppt
1
Agenda
• Part one: the big
picture
• Part two: the
mechanics
– The point of technical
writing
– The patterns
– The process
– Rules
– Reference sources
6 November 2007
–
–
–
–
–
–
–
Technical writing: part two
Data presentation
Figures
Proofs
Citation
The details
Appearance
Editing and markup
2
Abstract
• A reader uses this to see if a paper is likely
relevant and interesting
– So actually say what the paper is about!
• A librarian uses this to categorize papers to help
future readers
• Search software often uses this to find likely
relevant papers
• Relevant ⇒ say what problem the paper
addresses
• Interesting ⇒ say what is new and different
6 November 2007
Technical writing: part two
3
Good and bad examples (from van Leunen)
An advance in the definition
of certain operators is
made possible by the
application of several
recent results in
complexity. Full details
are supplied, and
illustrative examples are
included. Data on related
findings are presented in
the final section along
with implications for
further research.
6 November 2007
The operators Shift, Reply,
and VVX are not so week
as they first seemed. An
application of Browning’s
Theorem and his more
recent work on
conjunctivity suggest that
these operators impose
hidden constraints on
their members, which
may constitute a uniform
but as yet undefined set.
Technical writing: part two
4
The four-part abstract
• “I try to have four sentences in my abstract. The first
states the problem. The second states why the problem
is a problem. The third is my startling sentence. The
fourth states the implication of my startling sentence.”
- Kent Beck, OOPSLA’93 panel
• Addresses relevance and interest
• Extension: add a key experimental result fact backing up
the main claim
“The rejection rate for OOPSLA papers in near 90%. Most papers are
rejected not because of a lack of good ideas, but because they are
poorly structured. Following four simple steps in writing a paper will
dramatically increase your chances of acceptance. If everyone
followed these steps, the amount of communication in the object
community would increase, improving the rate of progress.”
6 November 2007
Technical writing: part two
5
Data presentation
• Use graphs, tables, and images to communicate
experimental results
• What matters:
– Clearly understanding the main points of the results
– Correct recording of the data
– Acknowledgement of uncertainty in the data
• Lot in the experimental results section(s), but
can happen in earlier explanatory text
– A good way to show why something matters
6 November 2007
Technical writing: part two
6
Good graphs
• Are readable
– Points and lines are readable and distinguishable
– Multiple curves are marked
• Are honest about the zero point
– Things that differ by 1% look different when one doesn’t go to zero
• Don’t use color
– Doesn’t reproduce
• Avoid excess marking and three-dimensional effects
– Clutters the data; 3D effects misrepresent data
• Show statistical significance
• Avoid “spin”
– Ratio games: show ratio of differences between things to make one
seem a lot better
– Better to report the metric that directly has value (such as latency)
6 November 2007
Technical writing: part two
7
Good and bad graphs
0.7
1.2
0.6
0.5
0.8
0.4
seconds
1
ratio to Type 1 0.6
Type 2
Type 3
Type 1
Type 2
Type 3
0.3
0.2
0.4
0.1
0.2
0
0
1
2
3
4
5
input force
6
0
7
4
6
8
10
input force
• Won’t reproduce
• Lots of flash that gets in the
way of the data
• Are the differences significant?
• Do the ratios actually matter?
6 November 2007
2
•
•
•
•
Contains actual data
Still missing confidence
Will reproduce properly
Smoothing is probably a lie
(unless backed up by analysis
in text)
Technical writing: part two
8
Figures
• Use them liberally to illustrate key ideas
• Don’t present more then around five or six ideas in any
one figure (max)
• Use consistent style
• Place figures near their first reference
• Use standard notations where appropriate
• Figures in English-language text should present
concepts left-to-right, top-to-bottom
• Minimize shading; don’t use color
– Repro issues
– Usability for people with colorblindness
6 November 2007
Technical writing: part two
9
Good and bad figures
• Doesn’t explain the point
being made
6 November 2007
• Fairly simple
• Shows main idea (data
propagation) in clockwise
flow from top
Technical writing: part two
10
Proofs
• The point of a proof is to persuade the reader of the
correctness of a proposition by logic (as opposed to
experimental evidence)
• Help the reader understand the chain of reasoning
– Give the reader a roadmap: say how the reasoning works at a
high level before getting into the details
– Lemmas are object-oriented proofs
Lemma 1. Chunks perform committed write actions for a
single block in strict timestamp order. That is, for any
two committed write actions ai and aj, i≠j, ai ∈ pred(aj) ⇒
ts(ai) < ts(aj).
6 November 2007
Technical writing: part two
11
Citation
• Warning: this is the most complex part of technical
writing but gets little attention
• Goals:
– Help the reader learn more (context, additional details, contrary
opinions)
– Acknowledge sources and ideas
– Give evidence to back up statements
• References must be able to find them 10 or 20 years
from when they are written
– Archival sources: web pages are particularly bad
– Don’t abbreviate: what is the EJCC and WJCC?
6 November 2007
Technical writing: part two
12
Citation (2)
• Get a good reference book—read it and follow it
• Inline usage:
– Citing the work of [Anderson02] is a bad thing.
– Much better to cite Anderson [2002].
– Note that citation is a part of the sentence [van Leunen 92].
• Always proofread your reference section
• It’s worth using a good tool for building the reference
section
– BibTeX is pretty good
6 November 2007
Technical writing: part two
13
Details
• Paragraph structure
– Intro sentence, body that expands on the intro
– One-sentence paragraphs are perfectly legal
• Layout
– Different conferences/journals have different layout
rules; be sure to follow them
– Especially important for theses
– Short line length is good
• Capitalization
– Upper and Lower Case Is Not a Good Idea
6 November 2007
Technical writing: part two
14
Details (2)
• Which versus that
– “that” is used to select from a set of things
– “which” is used to (parenthetically) report a property
of things
– “which” occurs usually after a comma
– There are other uses for both these words, which can
be confusing
– Assume there are three experiments
– The experiment that shows that performance is good
– The first experiment, which shows that things work
correctly
6 November 2007
Technical writing: part two
15
Details (3)
• Passive voice
– The tone of speaking that does not say who is doing
what is to be avoided
– A sentence should have an active subject
• Versus (vs.), for example (e.g.), that is (i.e.),
note (N.B.)
– Better to actually spell these out
– If you must, remember these are abbreviations of
Latin
– Properly italicized
• Define terms (especially acronyms) before using
them
6 November 2007
Technical writing: part two
16
Details (4)
• I versus we
– This is a matter of debate
– “The ‘we’ that means ‘I’ is always objectionable except in
monarchs, popes, and the front columns of The New Yorker.”
» van Leunen, A Handbook for Scholars
• Substitute “damn” every time you're inclined to write
“very”; your editor will delete it and the writing will be just
as it should be.
- Mark Twain (attributed)
6 November 2007
Technical writing: part two
17
Editing
QuickTime™ and a
TIFF (LZW) decompressor
are needed to see this picture.
6 November 2007
Technical writing: part two
18
Some rules
• Originality
• Don’t copy unless you quote.
• Don’t copy from yourself. When you sign over copyright, they
aren’t your words any more.
• Republication and copyright
• Can be complicated; each publisher has their own rules
• Preservation of data
• You are expected to preserve experimental data for “a long time”
• Not well established in computer science; legal requirement in
other fields -- but it’s a good idea
• Preservation of text
• Archival repositories
6 November 2007
Technical writing: part two
19
Final thoughts
1. Writing is really learned by doing.
2. Pay attention to good papers; try to figure out
what works about them.
3. All this has been a bunch of reminders. Drag it
out sometime when you have something to
write and read it over.
6 November 2007
Technical writing: part two
20
Resources
• A Handbook for Scholars. Mary-Clair van Leunen
(out of print, but about the best there is)
• Strunk & White
• The Visual Display of Quantitative Information, Edward Tufte
• The Chicago manual if you must
http://www.acm.org/sigs/sigplan/conferences/author-info/
http://www.ece.ucdavis.edu/~jowens/commonerrors.html
http://socrates.berkeley.edu/~schmid/articles/Schmid1983--which-hunting.html
http://www.cs.berkeley.edu/~pattrsn/talks/writingtips.html
http://www.cs.cmu.edu/~jrs/sins.html
http://gatekeeper.dec.com/pub/DEC/SRC/publications/levin/SOSPhowto.html
http://www.acm.org/sigs/sigplan/oopsla/oopsla96/how93.html (esp for paper structure and abstract
form)
http://www.cs.columbia.edu/~hgs/etc/writing-style.html
http://www.cs.cmu.edu/~mleone/how-to.html
http://www.cs.cmu.edu/~Compose/shaw-icse03.pdf
http://www.economist.com/research/styleGuide/
6 November 2007
Technical writing: part two
21