Technical Writing NISS ASA Workshop Washington DC 2
- Slides: 25
Technical Writing NISS – ASA Workshop Washington DC 2 – 5 August 2009
Writing for a Technical Audience o Purpose: To Inform o Aspects n Structure o Choice of Material o Organization of Ideas o Depth of Detail n Style o Grammatical Structure o Word Choice o Caveat: Don’t Lose the Reader!
Review Criteria o Technical Content o o o Correctness Significance Innovation Interest Timeliness o Writing o o o Succinctness Accessibility Elegance Readability Style Polish
A Technical Writer Is NOT: o J. K. Rowling o Kid at summer camp o Nora Roberts o Peter Mayle o Ken Follett o Dan Brown or Iain Pears o Alexandre Dumas o Thomas Hardy or Charles Dickens o Emily Bronte o D. H. Lawrence o Cervantes o Artur Perez-Reverte or Franz Kafka o Leo Tolstoy
A Technical Audience is NOT: On a QUEST o Challenge to participate o Obstacles to overcome, each more difficult than the one before o Prize for success o Penalty for failure
A Technical Audience is NOT: On a QUEST o Challenge to participate o Obstacles to overcome, each more difficult than the one before o Prize for success o Penalty for failure o Keywords o o Title Abstract Introduction Body of article n Section by section o Result n Theorem n Discussion/Conclusion
Starting Point o Decide Purpose o Identify Major Results o Determine Audience
Starting Point o Purpose n Breakthrough (ground-breaking) – new formulation to solve old or new open problem n Progress / development – often new methodology or extension to higher dimension, a new context, or relaxation of assumptions n Comparison of existing methods with/without modification n Reprise – new more elegant proof of known result yielding greater insight, often entirely new technical approach n Illustration – application to real problem/ data of importance, typical of other applications n Scientific result – not primarily statistical innovation n Summary – review of state-of-the-art
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: Science-driven Introduction Statistical Formulation of Problem Statement in Scientific Context Simple Case / Progression to General Case Primary Result Statistical Formulation of Problem Statement in Scientific Context with Implementation Primary Result Progressive Development of Model or Analysis Primary Result Discussion or Conclusions Implementation for Application (Primary Result)
Structure: Content o Selectivity n Less than everything n Specific Cases: Simple to General o Theorems, Corollaries, Lemmas o Methods, Analytic Techniques o Examples, Applications o Simulations o Alternatives n Discussion n Appendix n Technical report
Structure: Content o Importance n Most powerful n Most broadly usable n Most frequently applicable o Clarity n Most interpretable without extensive contextual information or explanation o Coherence n Consistently used throughout paper o Uniqueness *
Structure: Signposts o Goal: Provide reader with a map to the article n “You are here” and “What comes next” o Introduction n Outline for article, section by section o Section - preamble or paragraph n Outline for section o Overview of sequence of lemmas, theorems o Overview of model development, inferential method construction o Overview of data, analytic sequence
Structure: Signposts o Extensive proof or complex algorithm n Paragraph (as preamble) outlining proof or construction n Sentence (midway) summarizing what has been proved, what comes next o Outline for subsection n Introductory paragraph o Paragraph n Opening sentence stating purpose
Pre-First Draft o Written “Outline” n Purpose n Problem Statement n Signposts o To subsection level o Draft Abstract o Diagram n 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. 1 § A. 2 § A. 3
Choice of Material o Space allocation – by importance n Of result and its consequences n For making reasoning transparent o Critical steps and keys to solution o Proofs n “Substitute (#. #) into (#. ##) and apply Green’s theorem” o Construction / derivation of methodology n “Noting that (#. #) can be rewritten as a mixed model with correlated error structure, partitioning by. . . gives” o Application – orderly analysis n Principle finding through consequences
Choice of Material o Space allocation – by importance n Critical information o Requisite space required for clarity n OTHERWISE: Skip the obvious and summarize o “By straightforward but tedious algebra. . . “ o Following the proof by ***** in (reference) n NEVER by chronology of research process n NEVER by pain and suffering incurred to obtain result
Introduction o o o Goals n Convey Importance, Impact of research results n Attract readers Content n General Context o What is the problem? o Why care about the work? n Technical Context o What was already known? o What was the gap (before this paper)? n Contribution of this paper o What is the approach to (nature of) the solution? n Outline of paper – “Signposts” References within text n Natural choices, signal papers – not entire literature review n Citation without interrupting flow of text
Style: Transparent, Clear, Precise, Parsimonious, Concise, Spare, Lean, Direct o Overall Impression n “Careful writing reflects careful work” n Precise word usage – Standard English o 1: 1 Word: Concept n Precise notation usage o Definition before first use of notation or symbol o 1: 1 Notation: Definition o Numbered for internal referencing throughout text (as appropriate) o Repeated (brief) definition for delayed use or for modification (e. g. , dropping subscript) n Grammar! o Spell and grammar check n Useful n Neither Necessary nor Sufficient o References: Strunk & White
Style: Transparent, Clear, Precise, Parsimonious, Concise, Spare, Lean, Direct o Effective Writing n Verbs o ACTIVE not passive when possible o Correct verb tenses n Data Exist – Present (NOTE: Data ARE - plural) n Papers Exist – Present n Experiments End – Past n Theorems Hold - Present n Antecedents and References o 1: 1 or 1: many or many : 1 or many : many? o “the sequences induce graphs” n Singular rather than plural n “each sequence induces a graph”
Style: Transparent, Clear, Precise, Parsimonious, Concise, Spare, Lean, Direct o Effective Writing n Clear Sentences o CONSISTENT voice – either 1 st person (“I” or “we”) or 3 rd person o USE PARALLEL structure for series n Series of sentences n Series within sentences – clauses, verbs, objects o DISENTANGLE complex sentences n Reference numbering o Equations o Figures – all types o Definitions – if referred to later, especially for section -long gap
Style: Transparent, Clear, Precise, Parsimonious, Concise, Spare, Lean, Direct o “Do Not Litter” n DELETE: Wasted sentences n n Vague, overly general Only approximately (not precisely) true Unnecessarily repetitive “Mixed models are important to many areas of application. ” n DELETE: Wasted phrases and words n “It is easy to see that. . . ” n “In order to. . . ” (“To” almost always suffices) n Most adjectives, especially judgmental, emotional n REPLACE: Non-standard English n Personal words. . . You are not [yet] Tukey n Cute / funny / trendy / jargon /TXT expressions
Abstract: Illustration o 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 o o o 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 o Define symbols, terms, acronyms at first use (reference # if appropriate) o Avoid passive voice o Prefer specific/singular to general/plural o Make internal references clear o Choose best presentation (text, table, graph, figure) o Write clear (self-explanatory) captions o Find precise words; use words precisely o BE WILLING TO REVISE SEVERAL TIMES
- Vignette mutuelle 110/110
- Niss
- Etiquette hopital
- Rankin escala
- Niss wreck
- Writing workshop: narrative writing quiz
- Technical/academic writing
- Washington state board of technical and community colleges
- Technical writers in washington district of columbia
- Chapter 13: writing workshop -- résumés
- Document based questions
- Writing workshop framework
- Business plan writing workshop
- Proposal writing on career guidance workshop
- Career guidance presentation
- Proposal writing on career guidance workshop
- Technical report writing quiz
- What is technical style
- Characteristics of technical writing
- Example of technical writing
- Goal for technical writing
- Abcs of technical writing
- Minimalism in technical writing
- Style in technical writing
- Characteristics of technical writing
- Technical writing lesson plans