1. Technical Writing NISS – ASA Workshop Washington DC 2 – 5 August 2009

2. Writing for a Technical Audience  Purpose: To Inform  Aspects Structure  Choice of Material  Organization of Ideas  Depth of Detail Style  Grammatical Structure  Word Choice  Caveat: Don’t Lose the Reader!

3. Review Criteria  Technical Content  Correctness  Significance  Innovation  Interest  Timeliness  Writing  Succinctness  Accessibility  Elegance  Readability  Style  Polish

4. A Technical Writer Is NOT:  J.K. Rowling  Kid at summer camp  Nora Roberts  Peter Mayle  Ken Follett  Dan Brown or Iain Pears  Alexandre Dumas  Thomas Hardy or Charles Dickens  Emily Bronte  D.H. Lawrence  Cervantes  Artur Perez-Reverte or Franz Kafka  Leo Tolstoy

5. A Technical Audience is NOT: On a QUEST  Challenge to participate  Obstacles to overcome, each more difficult than the one before  Prize for success  Penalty for failure

6. A Technical Audience is NOT: On a QUEST  Challenge to participate  Obstacles to overcome, each more difficult than the one before  Prize for success  Penalty for failure  Keywords  Title  Abstract  Introduction  Body of article Section by section  Result Theorem Discussion/Conclusion

7. Starting Point  Decide Purpose  Identify Major Results  Determine Audience

8. Starting Point  Purpose Breakthrough (ground-breaking) – new formulation to solve old or new open problem Progress / development – often new methodology or extension to higher dimension, a new context, or relaxation of assumptions Comparison of existing methods with/without modification Reprise – new more elegant proof of known result yielding greater insight, often entirely new technical approach Illustration – application to real problem/ data of importance, typical of other applications Scientific result – not primarily statistical innovation Summary – review of state-of-the-art

9. Structure: Logical Introduction Problem Statement in Technical Form Sequence of Lemmas and Theorems Primary Result Example / Simulation / Proof of Concept Discussion or Conclusions Simple Case / Progression to General Case Primary Result Application Example / Simulation / Data Analysis

10. Structure: Science-driven Introduction Problem Statement in Scientific Context Discussion or Conclusions Progressive Development of Model or Analysis Primary Result Implementation for Application (Primary Result) Statistical Formulation of Problem Statement Simple Case / Progression to General Case Primary Result Problem Statement in Scientific Context with Implementation Primary Result Statistical Formulation of Problem Statement

11. Structure: Content  Selectivity Less than everything Specific Cases: Simple to General  Theorems, Corollaries, Lemmas  Methods, Analytic Techniques  Examples, Applications  Simulations  Alternatives Discussion Appendix Technical report

12. Structure: Content  Importance Most powerful Most broadly usable Most frequently applicable  Clarity Most interpretable without extensive contextual information or explanation  Coherence Consistently used throughout paper  Uniqueness *

13. Structure: Signposts  Goal: Provide reader with a map to the article “You are here” and “What comes next”  Introduction Outline for article, section by section  Section - preamble or paragraph Outline for section  Overview of sequence of lemmas, theorems  Overview of model development, inferential method construction  Overview of data, analytic sequence

14. Structure: Signposts  Extensive proof or complex algorithm Paragraph (as preamble) outlining proof or construction Sentence (midway) summarizing what has been proved, what comes next  Outline for subsection Introductory paragraph  Paragraph Opening sentence stating purpose

15. Pre-First Draft  Written “Outline” Purpose Problem Statement Signposts  To subsection level  Draft Abstract  Diagram Example – with application § 1.0 § 1.1 § 1.2 § 1.A § 2.0 § 2.1 § 2.A § 3.0 § 3.1 § 3.A § 1.0 § 1.1 § 1.2 § 2.0 § 3.0 § A.0 § A.1 § A.2 § A.3

16. Choice of Material  Space allocation – by importance Of result and its consequences For making reasoning transparent  Critical steps and keys to solution  Proofs “Substitute (#.#) into (#.##) and apply Green’s theorem”  Construction / derivation of methodology “Noting that (#.#) can be rewritten as a mixed model with correlated error structure, partitioning by... gives”  Application – orderly analysis Principle finding through consequences

17. Choice of Material  Space allocation – by importance Critical information  Requisite space required for clarity OTHERWISE: Skip the obvious and summarize  “By straightforward but tedious algebra... “  Following the proof by ***** in (reference) NEVER by chronology of research process NEVER by pain and suffering incurred to obtain result

18. Introduction  Goals Convey Importance, Impact of research results Attract readers  Content General Context  What is the problem?  Why care about the work? Technical Context  What was already known?  What was the gap (before this paper)? Contribution of this paper  What is the approach to (nature of) the solution? Outline of paper – “Signposts”  References within text Natural choices, signal papers – not entire literature review Citation without interrupting flow of text

19. Style: Transparent, Clear, Precise, Parsimonious, Concise, Spare, Lean, Direct  Overall Impression “Careful writing reflects careful work” Precise word usage – Standard English  1:1 Word:Concept Precise notation usage  Definition before first use of notation or symbol  1:1 Notation:Definition  Numbered for internal referencing throughout text (as appropriate)  Repeated (brief) definition for delayed use or for modification (e.g., dropping subscript) Grammar!  Spell and grammar check Useful Neither Necessary nor Sufficient  References: Strunk & White

20. Style: Transparent, Clear, Precise, Parsimonious, Concise, Spare, Lean, Direct  Effective Writing Verbs  ACTIVE not passive when possible  Correct verb tenses Data Exist – Present (NOTE: Data ARE - plural) Papers Exist – Present Experiments End – Past Theorems Hold - Present Antecedents and References  1:1 or 1: many or many : 1 or many : many?  “the sequences induce graphs” Singular rather than plural “each sequence induces a graph”

21. Style: Transparent, Clear, Precise, Parsimonious, Concise, Spare, Lean, Direct  Effective Writing Clear Sentences  CONSISTENT voice – either 1 st person (“I” or “we”) or 3 rd person  USE PARALLEL structure for series Series of sentences Series within sentences – clauses, verbs, objects  DISENTANGLE complex sentences Reference numbering  Equations  Figures – all types  Definitions – if referred to later, especially for section-long gap

22. Style: Transparent, Clear, Precise, Parsimonious, Concise, Spare, Lean, Direct  “Do Not Litter” DELETE: Wasted sentences Vague, overly general Only approximately (not precisely) true Unnecessarily repetitive “Mixed models are important to many areas of application.” DELETE: Wasted phrases and words “It is easy to see that...” “In order to...” (“To” almost always suffices) Most adjectives, especially judgmental, emotional REPLACE: Non-standard English Personal words... You are not [yet] Tukey Cute / funny / trendy / jargon /TXT expressions

23. Abstract: Illustration  This article proposes...[a general semiparametric model...]... This model provides... [tests]... This contrasts with previous approaches based on... We demonstrate that conditional likelihood is robust to... Its main advantages are that... A case study of...[spike data]... illustrates that this method...

24. Principles to Write by  Remember your goal: to inform  Know your purpose  Know your audience  Use “signposts” at every level  Give position, space and detail according to importance

25. Practices for Clear Writing  Define symbols, terms, acronyms at first use (reference # if appropriate)  Avoid passive voice  Prefer specific/singular to general/plural  Make internal references clear  Choose best presentation (text, table, graph, figure)  Write clear (self-explanatory) captions  Find precise words; use words precisely  BE WILLING TO REVISE SEVERAL TIMES