1 Technical writing part two Richard Golding IBM Almaden Research Center

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

6 November 2007Technical writing: part two3 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 2007Technical writing: part two4 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.

6 November 2007Technical writing: part two5 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 2007Technical writing: part two6 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 2007Technical writing: part two7 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 2007Technical writing: part two8 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)

6 November 2007Technical writing: part two9 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 2007Technical writing: part two10 Good and bad figures Doesn’t explain the point being made Fairly simple Shows main idea (data propagation) in clockwise flow from top

6 November 2007Technical writing: part two11 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 a i and a j, i≠j, a i ∈ pred(a j ) ⇒ ts(a i ) < ts(a j ).

6 November 2007Technical writing: part two12 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 2007Technical writing: part two13 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 2007Technical writing: part two14 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 2007Technical writing: part two15 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 2007Technical writing: part two16 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 2007Technical writing: part two17 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 2007Technical writing: part two18 Editing

6 November 2007Technical writing: part two19 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 2007Technical writing: part two20 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 2007Technical writing: part two21 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 (esp for paper structure and abstract form)