Technical Writing Course
Abelard Consulting is of the view that giving participants in a training course just the
presentation slides to take away with them does not provide them with the best opportunity
to reinforce their learning once they are back in the workplace. A slide can be meaningless
when divorced from the context set by the facilitator during training. To maximise the
opportunity for post‐training reinforcement, Abelard Consulting provides each participant
with a guide that doubles as a textbook. All the topics covered in the course are treated at
length in the guide, but the guide also includes many other topics (all relevant to language and
communication). Thus the guide can be used both to reinforce what participants learn during
the course and to provide an opportunity, through self‐paced study, to build on that learning. Participants in Abelard Consulting’s two‐day public technical writing course receive a 363‐
page reference book. This book—which is fully indexed—covers in detail all the topics
covered in the course and substantially more. To give you an idea of the topics covered in the
course, the contents pages of the reference book are reproduced below. (Participants in our
corporate courses—those provided in‐house to a single client—receive a slightly modified
book of approximately 325 pages.)
For more information about this course, call 1800 601 116 (a free call from within Australia) or
send an email to [email protected].
Contents
1Introduction
11
About the course
11
What is technical writing?
12
Prescriptivist view 12 Descriptivist view 12
The long history of technical writing
13
New name for an old profession
14
What do technical writers produce nowadays?
14
Why
good
technical writing matters
14
Professional ethics 14 Ethics pure and simple 14
The law 15
But no one reads user documentation, right? 16 The value the profession adds: commercial benefits 16
2 General Principles of Good Technical Writing
18
Maximum communicative efficiency
18
Five essential attributes of good factual writing 19
Clarity 19
Ambiguity 20 Vagueness 25
Familiarity 27
Familiar vocabulary 27 Familiar meaning 30
Familiar idioms 30
Familiar grammar, spelling and punctuation 31
get brochure book online home page
Familiar signs and symbols 32 Familiar numerical representation, units and symbols 32
Economy 33
Verbosity 33 Triviality 33 Redundancy 34 Tautology 34 Over-precision 34 Padding 35
Neutrality 35
Techniques for avoiding sexism 37
Consistency 38
The principle of single and distinct denotation 38 Techniques for controlling vocabulary and styles 39
But what about correct writing?
39
Putting practices and conventions into perspective 41 The primacy of communicative efficiency 42
Summary 42
Exercise 1
44
Post-break activities: Day 1
46
3 The Language of Language
47
Objectives 47
The importance of knowing the language of language
47
The parts of speech
48
Nouns 48 Pronouns 51 Verbs 54 Adjectives 58 Adverbs 60 Conjunctions 61 Prepositions 62 Determiners 62 Interjections 63
Person 64
Structural elements
64
Phrase 65 Clause 66 Sentence 67 Paragraphs 68
Exercise 2
74
4 The Process of Writing: Strategies, Tips and Tricks
77
Objectives 77
The typical writing process
77
Research 78
Planning 78
Ingredients 79 Audience analysis 80 Choosing the type of deliverable 82
Estimating 84
Getting started: Overcoming writer’s block
85
Project journal 85
Tips from ancient Greek philosophy 86 Edward Albee technique 89 Brainstorming 89
Mind mapping 90
Outlining 91
Design issues
92
Document design 93
Page design 94
Content design 95
Online or print? 97 Economical fonts 98 Designing for structure 99
Templates 102
Usability issues
103
Being easy to find 103 Easy to understand 104
Easy to apply 104
Some usability considerations 104
The first draft
105
Reviewing 107
Peer review 107
Technical review 111 When you are the reviewer 112
Pre-publication tasks
112
Pre-publication tasks
112
5 Writing Step-by-Step Procedures
115
Objectives 115
Definition 115
Warm-up exercise
115
Anatomy of a procedure
117
Title 117 Overview 117 Prerequisites 117 Risk statements 118 References 118 Steps 118
Related tasks 119
Style 119
Title 119 Steps 120
Specifying risks
121
Where to place risk messages 121
How long should a procedure be?
122
The so-called 7 ± 2 rule 123
Common problems in procedure writing
123
Branching and chunking
129
Branching 129 Chunking 129
Exercise 3
133
6 Aspects of Grammar
137
Objectives 137
Grammar: what is it?
137
Some old rules not worth worrying about
138
Splitting infinitives 138 Stranded prepositions 138 Beginning a sentence with and or but 139
Revisiting
be
140
Common problems of grammar
141
Verb–subject agreement 141 Interrogatives 151 Subject–pronoun agreement 151 Relative clauses 152 Comparatives and superlatives 155
Exercise 4
158
7 Obstacles to Readability
159
Objectives 159
Mechanics versus style
159
The roots of good style
160
Common problems
161
Sentence: overly long and poorly varied 161 Overly dense sentences 165 Misplaced jargon 165 Overly pre-modified nouns 166 Noun clustering 168 Nominalisation 170 Voice: active or passive? 171 Impersonal constructions 173 Register 174
Readability formulas
175
Flesch Reading Ease Formula (FREF) 175 Readability statistics and passive sentences 177
Exercise 5
179
Post-break activities: Day 2
181
8 Troublesome Words
182
Words to watch
182
9 Punctuation Refresher
194
Terminology 194
The purpose of punctuation
195
Grammatical purpose 195 Emphatic purpose 195
Is punctuation important?
195
Vital punctuation 195 Discretionary punctuation 196
Fads worth forgetting
197
Descriptor fragments in parentheses or between dashes 197 Colons introducing a run-on list 198 Over-capitalisation 199
Lazy quotes 199
Solidus (/): a mark to be mostly avoided 200 Exclamation marks (!) 201 Singular–plural composites 202
Where punctuation is vital to meaning
202
Apostrophes 202
En dashes 206
Marking off parenthetic material 208 Dashes and similar characters: a summary 211 Commas in general 211 Serial commas: sometimes they are important 215 Hyphens and compound adjectives 216 Semicolons 218 Colons 220
Other punctuation marks
222
Brackets 222 Ellipsis (aka ellipsis points) 224 Quotation marks (aka inverted commas) 225
Exercise 6
231
10 Reports: Structure, Content & Strategies
233
Objectives 233
Introduction 233
Classifying reports
234
Informal reports 234
Formal reports 235
Classifying by purpose 235 Classifying by structure 235
Sample reports
236
Simple structure: a field report 236 Expository structure: a feasibility report 237 Narrative structure: a laboratory report 238 Pyramidal structure: an overlay for other report types 238
The IMRAD structure
238
Sections in a typical contemporary report
239
Title page 240
Document control and signoff 241 Abstract and keywords 242 Executive summary 244 Contents 245 Lists of figures and tables 245 List of shortened forms 245 Glossary 246 Introduction 246 Body: general reports 247 Body: scientific reports 248 Conclusion 251 Acknowledgements 252 Appendixes 252
Endnotes 252 References 252 Index 252
Citation systems and styles
253
The author–date system 253 Vancouver system 254 Other citation systems 255
Bibliographies and reference lists
255
Citation and footnotes 255 Style guidelines: author–date system 256 Style guidelines: Vancouver system 259 Citation–name system 260
White papers
260
Common problems in white papers 261
Responding to requests for tender (RFTs)
261
Ten common reasons why tender proposals fail 263
Visuals 263
When to use tables 264 Table structure 264 Types of figures 265 Figure structure 267
Common problems in reports
268
Poor font choice 268
Poor call-outs 269
Inconsistent styles 269 Misleading heading hierarchy 270 Pagination issues 270 Internal contradictions 271 Figures that don’t support the text 271 Figures that could easily mislead 271 Plagiarism and fabrication 273 Sloppy citing and referencing 274
Exercise 7
275
11 Reports: Reasoning & Logic
278
Objectives 278
Introduction 278
Reasoning 279
Logical reasoning 280 Sound reasoning 281
Common fallacies
282
Petitio principii 283 Affirming the consequent 283 Denying the antecedent 284 Post hoc ergo propter hoc 285 Fallacious styles of reasoning 286
Assessing the strength of a premise
287
a priori knowledge 288
a posteriori knowledge 288
Derivative knowledge 288
12 New Practices in Technical Writing
293
Objectives 293
Adobe Acrobat 3D
293
Single-sourcing 293
Content management systems
294
XML 294
Structured authoring
294
Collaborative authoring: the rise of wikis
296
13 Breaking into Technical Writing
299
Objectives 299
Why work as a technical writer?
299
Finding a job as a technical writer
299
Writing a CV
300
What pay can I expect?
300
Pros of being a contractor
301
Cons of being a contractor
301
A Answers to Exercises
305
Exercise 1
305
Exercise 2
306
Exercise 3
308
Exercise 4
311
Exercise 5
312
Exercise 6
313
Exercise 7
314
Exercise 8
316
Other exercises
317
Flowchart exercise
318
Decision table exercise
319
B Bloated Language
321
C Numbers, Symbols & Measurements
324
Words or numerals?
324
Fractions 325
Percentages 325
Dates and time
325
Digit separators
327
Numbers in equations
329
Types of symbols
329
Quantity symbols: variables and physical constants 329 Unit symbols: symbols of measurement 330 Descriptive symbols 332
D Methods of Controlling Vocabulary
333
Simplified English
333
Subject-specific thesauri
334
Project journals
336
Editing style sheets
338
E Entering Uncommon Characters
341
How do I find the code for a Unicode character? 342 Entering a Unicode character 343 Sample characters 344 What about the web? 345
F Variants of the English Language
346
American English
346
British English
348
Other variations 348
G Editors’ Checklists
349
Copy-editing checklist 349
Structural editing checklist
350
Content edit checklist
351
Proof-reading checklist
352
H Common Proof-reading Marks
354
I Sample Estimating Algorithms
357
J Writing Emails
359
Adopting the right register (aka tone)
359
Common structures
360
The Issue–Description–Action (IDA) approach 360 The MADE approach 361 The Executive Summary approach 362
Writing tips
363
Attitudinal writing
365
K Professional Societies & Other Resources
366
Professional societies
366
Local 366 Overseas 366
