Transcript F6 project analysis

Technical writing
part one
Richard Golding
IBM Almaden Research Center
www.chrysaetos.org/papers/Writing-1-2007-10-23.ppt
1
Agenda
• Part one: the big
picture
• Part two: the
mechanics
– The point of technical
writing
– The patterns
– The process
– Rules
– Reference sources
23 October 2007
–
–
–
–
–
–
–
Data presentation
Figures
Proofs
Citation
The details
Appearance
Editing and markup
Technical writing: part one
2
The scientific method
•
•
•
•
•
Context / problem
Hypothesis
Experiment
Results
Conclusion about hypothesis
23 October 2007
Technical writing: part one
3
Why writing matters
• Writing and communicating your work is one half
of the job of a researcher or an engineer
• If only you understand about a system, what’s
the point?
• This is the opposite of business concerns
• Key idea here: communication and teaching
from you to other people
23 October 2007
Technical writing: part one
4
Three essentials
1. Present a single clear truth
•
Not the journey; this is not a mystery story
2. One thing, not everything
•
Chances are you have a lot of papers to write
anyway
3. Teach the reader something useful
•
•
Especially how to think about a problem
How to reproduce the work
23 October 2007
Technical writing: part one
5
Patterns
• Technical writing follows formulae
• Innovation in presentation is bad
• Innovation in the content is good
• Structure of a paper
•
•
•
•
•
Overall section structure
Author list
Abstract
Hierarchical structure of text
Setting work in context
23 October 2007
Technical writing: part one
6
Overall section structure
•
•
•
•
•
Title
Authors
Abstract
Introduction
Body sections
• Related work
• There are templates for different communities
• Conclusions
• Acknowledgements (optional)
• References
23 October 2007
Technical writing: part one
7
The hierarchical structure of technical writing
• Start with a story
• A traversal of a tree, not a linear story
• Plus “roadmaps”
• The “first sentence” rule
23 October 2007
Technical writing: part one
8
A story
• What is the idea of the paper, stated succinctly?
• 3-5 sentences maximum
• Follow the template of the scientific method
–
–
–
–
–
Context (problem)
Hypothesis (problem solution)
Experiment (how to evaluate the solution)
Data (evaluation results)
Conclusion (how well the solution solves the problem)
23 October 2007
Technical writing: part one
9
A story: example
• Need performance
management when there is
shared storage
– There are several specific use
cases
• The performance needs of the
cases can be expressed
simply
• Use that to translate
performance needs into
common representation
• Schedule I/Os according to
that common representation
• Demonstrate the use cases to
show it works well
23 October 2007
Technical writing: part one
10
Hierarchy
23 October 2007
Technical writing: part one
11
Traversal
1. Introduction (whole paper,
problem context)
2. System model
3. Scheduling algorithm
4. Evaluation
1.
2.
3.
4.
Introduction (whole subtree)
Methodology
Microbenchmarks
Variations
1. …
5. Whole systems
6. Conclusions about evaluation
5. Related work
6. Conclusions (whole paper)
23 October 2007
Technical writing: part one
12
The first sentence rule
• Read the first sentence of every paragraph
• Must get all the ideas in the paper
• Important because this is how people skim
material
• Reflection of the hierarchical idea of writing
– Topic sentence for each paragraph
– Body of paragraph adds supporting detail to topic
sentence
23 October 2007
Technical writing: part one
13
Setting work in context
• The reader needs to know what problem this
solves
– Why should they care?
– If they have a problem to solve, does this address
their problem?
• Compare to solutions to similar problems
• Or to other solutions to the problem
23 October 2007
Technical writing: part one
14
The title
• Goal: reader knows in general what the paper is
about, so they can decide whether it’s likely
useful to their problem
• Say what the general subject is in the title
•
•
•
•
•
Keep it short
Keep it specific
Don’t be clever
Don’t claim more than you show
Two-part (colon) titles are overrated affectation
23 October 2007
Technical writing: part one
15
The title: examples
• Good: The LRU-K page replacement algorithm for
database disk buffering
• Not bad: Predicting file system actions from prior events
• Not bad: MapReduce: simplified data processing on
large clusters
• Annoying: Improved dynamic programs for batching
problems with maximum lateness criterion
• The author has many papers on this subject; which one is this?
• Too clever: Idleness is not sloth
• What is the applicability of this paper?
• Grandiose: Disk scheduling with quality of service
guarantees
• Presents one algorithm, not the whole topic
23 October 2007
Technical writing: part one
16
Author list
• All the authors who materially contributed to the writing
• Not necessarily everyone who did any work on the project
• Not necessarily the person who had the idea (though that’s
unusual)
• Being on the list creates a legal and ethical responsibility
• Each author is certifying that the work is correct
• Each author must be able to say what they did, and what each
other author did
• Order is by convention: first author is “most important”
• Often a source of acrimony; best to pick some rules
• Mechanics:
• Pick a way you present your name, and always use that
• Author’s affiliation is as of the time of the work; acknowledge
new affiliation in a footnote
• Some publishers have special rules (example: IEEE)
23 October 2007
Technical writing: part one
17
Abstract
• A reader uses this to see if a paper is likely
relevant and interesting
• 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
23 October 2007
Technical writing: part one
18
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.”
23 October 2007
Technical writing: part one
19
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
23 October 2007
Technical writing: part one
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/
23 October 2007
Technical writing: part one
21