Presentation is loading. Please wait.

Presentation is loading. Please wait.

Technical Writing NISS – ASA Workshop JSM Salt Lake City 29 July – 1 August.

Similar presentations


Presentation on theme: "Technical Writing NISS – ASA Workshop JSM Salt Lake City 29 July – 1 August."— Presentation transcript:

1 Technical Writing NISS – ASA Workshop JSM Salt Lake City 29 July – 1 August

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 A Technical Writer Is NOT:  J.K. Rowling  Kid at summer camp  Norah 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

4 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

5 Starting Point  Decide 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  Identify Major Results  Determine Audience

6 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

7 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  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

8 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

9 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 OTHERWISE: Skip the obvious and summarize  “By straightforward but tedious algebra... “  Following the proof by ***** in (reference) NOT by chronology of research NOT by pain of obtaining result

10 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

11 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

12 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 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

13 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

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


Download ppt "Technical Writing NISS – ASA Workshop JSM Salt Lake City 29 July – 1 August."

Similar presentations


Ads by Google