1 Technical writing part one Richard Golding IBM Almaden Research Center .

1

Technical writingpart one

Richard Golding

IBM Almaden Research Center

www.chrysaetos.org/papers/Writing-1-2007-10-23.ppt

23 October 2007 Technical writing: part one 2

Agenda

• Part one: the big picture– The point of technical

writing– The patterns– The process– Rules– Reference sources

• Part two: the mechanics– Data presentation– Figures– Proofs– Citation– The details– Appearance– Editing and markup


The scientific method

• Context / problem• Hypothesis• Experiment• Results• Conclusion about hypothesis


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


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


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


Overall section structure

• Title• Authors• Abstract• Introduction• Body sections

• Related work• There are templates for different communities

• Conclusions• Acknowledgements (optional)• References


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


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)


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


Hierarchy


Traversal

1. Introduction (whole paper, problem context)

2. System model

3. Scheduling algorithm

4. Evaluation1. Introduction (whole subtree)

2. Methodology

3. Microbenchmarks

4. Variations1. …

5. Whole systems

6. Conclusions about evaluation

5. Related work

6. Conclusions (whole paper)


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


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


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


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


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)


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⇒


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.”


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


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.htmlhttp://socrates.berkeley.edu/~schmid/articles/Schmid1983--which-hunting.htmlhttp://www.cs.berkeley.edu/~pattrsn/talks/writingtips.htmlhttp://www.cs.cmu.edu/~jrs/sins.htmlhttp://gatekeeper.dec.com/pub/DEC/SRC/publications/levin/SOSPhowto.htmlhttp://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.htmlhttp://www.cs.cmu.edu/~mleone/how-to.htmlhttp://www.cs.cmu.edu/~Compose/shaw-icse03.pdfhttp://www.economist.com/research/styleGuide/

1 Technical writing part one Richard Golding IBM Almaden Research Center .

Documents

Transcript of 1 Technical writing part one Richard Golding IBM Almaden Research Center .