Technical Writing

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 Dont 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 NOTOn 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
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
Pre-First Draft

• Written Outline
• Purpose
• Problem Statement
• Signposts
• To subsection level
• Draft Abstract

• Diagram
• Example with application

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 Greens
  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
• 11 WordConcept
• Precise notation usage
• Definition before first use of notation or symbol
• 11 NotationDefinition
• 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 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. . .