1 / 14

Technical Writing

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 : Don’t Lose the Reader!.

ivanbritt
Télécharger la présentation

Technical Writing

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

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. 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 A Technical Writer Is NOT:

  4. 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 A Technical Audience is NOT:On a QUEST

  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 Simple Case / Progression to General Case Primary Result Application Example / Simulation / Data Analysis Example / Simulation / Proof of Concept Discussion or Conclusions

  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. Written “Outline” Purpose Problem Statement Signposts To subsection level Draft Abstract Diagram Example – with application Pre-First Draft § 1.0 § 1.1 § 1.2 § 2.0 § 3.0 § A.0 § A.1 § A.2 § A.3 § 1.0 § 1.1 § 1.2 § 1.A § 2.0 § 2.1 § 2.A § 3.0 § 3.1 § 3.A

  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 1st person (“I” or “we”) or 3rd person • USE PARALLELstructure 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. . .

More Related