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

1

Technical writingpart two

Richard Golding

IBM Almaden Research Center

www.chrysaetos.org/papers/Writing-2-2007-11-6.ppt

6 November 2007 Technical writing: part two 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


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⇒


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.

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.


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


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


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)


Good and bad graphs

• Won’t reproduce• Lots of flash that gets in the

way of the data• Are the differences significant?• Do the ratios actually matter?

• Contains actual data• Still missing confidence• Will reproduce properly• Smoothing is probably a lie

(unless backed up by analysis in text)

0

0.2

0.4

0.6

0.8

1

1.2

ratio to Type 1

1 2 3 4 5 6 7input force

Type 2Type 3

0

0.1

0.2

0.3

0.4

0.5

0.6

0.7

0 2 4 6 8 10

input force

seconds

Type 1Type 2Type 3


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


Good and bad figures

• Doesn’t explain the point being made

• Fairly simple• Shows main idea (data

propagation) in clockwise flow from top


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


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?


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


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


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


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


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)


Editing

QuickTime™ and aTIFF (LZW) decompressor

are needed to see this picture.


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


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.


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 two Richard Golding IBM Almaden Research Center .

Documents

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