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