Technical Writing.ppt

1、Technical Writing,NISS ASA Workshop JSM Salt Lake City 29 July 1 August,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: Dont Lose the Reader!,A Technical Writer Is NOT:,J.K.

2、 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,A Technical Audience is NOT: On a QUEST,Challenge to participate Obstacles to

3、overcome, each more difficult than the one beforePrize for success Penalty for failure,KeywordsTitle Abstract Introduction Body of article Section by section Result Theorem Discussion/Conclusion,Starting Point,Decide Purpose Breakthrough (ground-breaking) new formulation to solve old or new open pro

4、blem 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 Illu

5、stration application to real problem/ data of importance, typical of other applications Scientific result not primarily statistical innovation Identify Major Results Determine Audience,Structure: Logical,Introduction,Problem Statement in Technical Form,Sequence of Lemmas and Theorems Primary Result,

6、Example / Simulation / Proof of Concept,Discussion or Conclusions,Simple Case / Progression to General Case Primary Result,Application Example / Simulation / Data Analysis,Structure: Signposts,Goal: Provide reader with a map to the article “You are here” and “What comes next” Introduction Outline fo

7、r 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 o

8、r construction Sentence (midway) summarizing what has been proved, what comes next Outline for subsection introductory paragraph Paragraph opening sentence stating purpose,Pre-First Draft,Written “Outline” Purpose Problem Statement Signposts To subsection levelDraft Abstract,Diagram Example with app

9、lication, 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,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 Greens theorem” C

10、onstruction / 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 alg

11、ebra. . . “ Following the proof by * in (reference) NOT by chronology of research NOT by pain of obtaining result,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

12、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,Style: Transparent, Cle

13、ar, 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 t

14、hroughout 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,Style: Transparent, Clear, Precise, Parsimonious, Concise, Spare, Lean, Direc

15、t,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 1st person (“I” or “we”) or 3rd person USE PARALLEL structure for seri

16、es 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,Style: Transparent, Clear, Precise, Parsimonious, Concise, Spare, Lean, Direct,“Do No

17、t 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 ad

18、jectives, especially judgmental, emotional REPLACE: Non-standard English Personal words . . . You are not yet Tukey Cute / funny / trendy / jargon /TXT expressions,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. . .,