Transcript Technical Writing Tutorial

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!
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
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
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
Structure: Logical
Introduction
Problem Statement
in Technical Form
Sequence of Lemmas
and Theorems
Primary Result
Simple Case / Progression
to General Case
Primary Result
Example / Simulation /
Proof of Concept
Application Example /
Simulation / Data Analysis
Discussion or
Conclusions
Structure: Signposts



Goal: Provide reader with a map to the article

“You are here” and “What comes next”

Outline for article, section by section

Outline for section
Introduction
Section - preamble or paragraph




Extensive proof or complex algorithm




Overview of sequence of lemmas, theorems
Overview of model development, inferential method
construction
Overview of data, analytic sequence
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
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
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”

“Noting that (#.#) can be rewritten as a mixed model with
correlated error structure, partitioning by . . . gives”
 Construction / derivation of methodology
 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
Introduction


Goals
 Convey Importance, Impact of research results

Attract readers


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”


Natural choices, signal papers – not entire literature review
Citation without interrupting flow of text
Content



References within text
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
Style:
Transparent, Clear, Precise,
Parsimonious, Concise, Spare, Lean, Direct

Effective Writing

Verbs


ACTIVE not passive when possible
Correct verb tenses





Clear Sentences


CONSISTENT voice – either 1st person (“I” or “we”) or 3rd person
USE PARALLEL structure for series



Data Exist – Present (NOTE: Data ARE - plural)
Papers Exist – Present
Experiments End – Past
Theorems Hold - Present
Series of sentences
Series within sentences – clauses, verbs, objects

DISENTANGLE complex sentences



Equations
Figures – all types
Definitions – if referred to later, especially for section-long gap
Reference numbering
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
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. . .