1 Technical writing part one Richard Golding IBM Almaden Research Center

23 October 2007Technical writing: part one2 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

23 October 2007Technical writing: part one3 The scientific method Context / problem Hypothesis Experiment Results Conclusion about hypothesis

23 October 2007Technical writing: part one4 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 2007Technical writing: part one5 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 2007Technical writing: part one6 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 2007Technical writing: part one7 Overall section structure Title Authors Abstract Introduction Body sections Related work There are templates for different communities Conclusions Acknowledgements (optional) References

23 October 2007Technical writing: part one8 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 2007Technical writing: part one9 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 2007Technical writing: part one10 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 2007Technical writing: part one11 Hierarchy

23 October 2007Technical writing: part one12 Traversal 1.Introduction (whole paper, problem context) 2.System model 3.Scheduling algorithm 4.Evaluation 1.Introduction (whole subtree) 2.Methodology 3.Microbenchmarks 4.Variations 1.… 5.Whole systems 6.Conclusions about evaluation 5.Related work 6.Conclusions (whole paper)

23 October 2007Technical writing: part one13 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 2007Technical writing: part one14 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 2007Technical writing: part one15 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 2007Technical writing: part one16 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 2007Technical writing: part one17 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 2007Technical writing: part one18 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 2007Technical writing: part one19 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 2007Technical writing: part one20 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 2007Technical writing: part one21 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)