Technical writing part one Richard Golding IBM Almaden

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: Map. Reduce: 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/Schmid 1983 --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 96/how 93. 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-icse 03. pdf http: //www. economist. com/research/style. Guide/ 23 October 2007 Technical writing: part one 21