Technical Writing Course

Transcription

1 Abelard Consulting Technical Writing Course get brochure book online home page 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 (a free call from within Australia) or send an to courses@abelard.com.au. 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

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

3 3 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 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 Visualising tasks and processes 131

4 4 Exercise 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 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 Post-break activities: Day Troublesome Words 182 Words to watch 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

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

6 6 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 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 Exercise 8 291

7 7 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 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 Exercise Exercise Exercise Exercise Exercise Exercise Exercise 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 Style guides 340

8 8 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 s 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 Online discussion forums 367 L Bibliography 368 Index 370 get brochure book online home page