Technical Writing

NISS – ASA WorkshopWashington DC2 – 5 August 2009

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!

Review Criteria Technical Content

Correctness Significance Innovation Interest Timeliness

Writing Succinctness Accessibility Elegance Readability Style Polish

A Technical Writer Is NOT: J.K. Rowling Kid at summer

camp Nora 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

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

Identify Major Results

Determine Audience

Starting Point 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 Summary – review of state-of-the-art

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

Structure: Science-driven Introduction

Problem Statement in Scientific Context

Discussion or Conclusions

Progressive Development of Model or Analysis Primary Result

Implementation for Application (Primary Result)

Statistical Formulation of Problem Statement

Simple Case / Progression to General Case Primary Result

Problem Statement in Scientific Context with Implementation Primary Result

Statistical Formulation of Problem Statement

Structure: Content

Selectivity Less than everything Specific Cases: Simple to General

Theorems, Corollaries, Lemmas Methods, Analytic Techniques Examples, Applications Simulations

Alternatives Discussion Appendix Technical report

Structure: Content

Importance Most powerful Most broadly usable Most frequently applicable

Clarity Most interpretable without extensive contextual

information or explanation

Coherence Consistently used throughout paper

Uniqueness *

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

Structure: Signposts 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

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”

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

Choice of Material Space allocation – by importance

Critical information Requisite space required for clarity

OTHERWISE: Skip the obvious and summarize “By straightforward but tedious algebra. . . “ Following the proof by ***** in (reference)

NEVER by chronology of research process NEVER by pain and suffering incurred to

obtain 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 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, 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

Data Exist – Present (NOTE: Data ARE - plural) Papers Exist – Present Experiments End – Past Theorems Hold - Present

Antecedents and References 1:1 or 1: many or many : 1 or many : many? “the sequences induce graphs”

Singular rather than plural “each sequence induces a graph”

Style: Transparent, Clear, Precise, Parsimonious, Concise, Spare, Lean, Direct

Effective Writing 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

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

Principles to Write by

Remember your goal: to inform Know your purpose Know your audience Use “signposts” at every level Give position, space and detail according

to importance

Practices for Clear Writing Define symbols, terms, acronyms at first use

(reference # if appropriate) Avoid passive voice Prefer specific/singular to general/plural Make internal references clear Choose best presentation (text, table, graph,

figure) Write clear (self-explanatory) captions Find precise words; use words precisely BE WILLING TO REVISE SEVERAL TIMES