A Strategic Guide to Effective Technical Communication

309 Pages·2007·3.199 MB·English

by  Heather Graves, Roger Graves

This electronic material is under
copyright protection and is
provided to a single recipient
for review purposes only.
Review Copy
A Strategic Guide to
Technical Communication
Review Copy
A Strategic Guide to
Technical Communication
Heather Graves and Roger Graves
broadview press
Review Copy
© 2007 Heather Graves and Roger Graves
north america All rights reserved. The use of any part of this publication reproduced,
Post Office Box 1243, transmitted in any form or by any means, electronic, mechanical, photo-
Peterborough, Ontario, copying, recording, or otherwise, or stored in a retrieval system, without
Canada k9j 7h5 prior written consent of the publisher—or in the case of photocopying, a
licence from Access Copyright (Canadian Copyright Licensing Agency),
Post Office Box 1015,
One Yonge Street, Suite 1900, Toronto, Ontario m5e 1e5—is an infringe-
3576 California Road,
ment of the copyright law.
Orchard Park, New York,
uSA 14127
library and archives canada cataloguing in publication
tel: [phone]
fax: [phone]
Graves, Heather, 1958-
email: A strategic guide to technical communication/Heather
customerservice@ Graves and Roger Graves.
broadviewpress.com
Includes bibliographical references and index.
uk, ireland, & ISBN 978-1-55111-814-7
continental europe
NBN International, Estover Road, 1. Technical writing. 2. Communication of technical information.
Plymouth, uK pl6 7py I. Graves, Roger, 1957– II. Title.
tel: [phone]
fax: [phone] T11.G738 2007 808’.0666 C2007-901990-0
email:
[email protected] broadview press is an independent, international publishing house,
incorporated in 1985. Broadview believes in shared ownership, both with
australia & new zealand its employees and with the general public; since the year 2000 Broadview
unireps university of New shares have traded publicly on the Toronto Venture Exchange under the
South Wales symbol bdp.
Sydney, NSW 2052 Australia
tel: [phone] We welcome comments and suggestions regarding any aspect of our
fax: [phone] publications—please feel free to contact us at the addresses below or at
[email protected]
email: www.broadviewpress.com.
[email protected]
Broadview Press acknowledges the financial support of the Government
of Canada through the Book Publishing Industry Development Program
(bpidp) for our publishing activities.
Cover design by Lisa Brawn
Interior by Em Dash Design
Printed in Canada
This book is printed on paper
containing 100% post-consumer fibre
Review Copy
Contents
preface 17
one thinking about audience, purpose, and
genre 29
What is technical communication? 29
How does it differ from other types of writing? 29
in-class exercise 1.1
Applying the Communication Triangle to Sample Documents 31
in-class exercise 1.2
Analysing Documents with Multiple Aims 32
Creative vs. technical writing 32
Who are these “users”? 32
Ways of Thinking About Users 33
in-class exercise 1.3
Analysing Multiple Audiences for Documents 35
How do you learn about your users? 35
Interview users 36
Observe users 36
Interview experts 37
Create user profiles 37
sample profiles 37
in-class exercise 1.4
Write a User Profile 37
Reaching your primary users 37
Why are you writing? 37
lab assignment 1.1
Characterizing Your Users 38
What is genre? 40
lab assignment 1.2
Linking Purpose and Audience 41
What are the main genres of technical
communication? 42
Why does genre matter? 43
Review Copy
6 a strategic guide to technical communication
What are genre sets? 43
How are the documents in genre sets
interdependent? 43
What are the conventions of the application letter? 45
What role does the résumé play in this genre set? 45
major project 1.1
The Job Application Package 49
two leading and misleading the reader:
ethical issues of technical communication 51
Ethics at work 51
Ethics for students 52
How is ethics related to technical communication? 55
Copyright, trademarks, and patents 56
What is not copyrightable 58
Rules for copying images 58
Writing ethically 59
Plain language guidelines 61
in-class exercise 2.1
Revising for Plain Language #1 63
using visuals ethically to communicate effectively 63
in-class exercise 2.2
Revising for Plain Language #2 64
What are the “right ways ... to show data”? 64
Select the right visual for telling that story 64
pie charts 64
line graphs 65
bar charts 66
dot charts 66
tables 67
maps 67
photographs 67
line drawings 67
gantt charts 68
Use the conventions for typical visuals 68
1. a title 68
2. all units labelled 68
3. source of the data 69
4. source of visual 69
in-class exercise 2.3
What Does a Gantt Chart Contribute to the Work Schedule? 70
Visuals that confuse or mislead 70
lab assignment 2.1
Evaluating Visuals 71
lab assignment 2.2
Creating Interesting Visuals 72
Review Copy
a strategic guide to technical communication contents 7
lab assignment 2.3
Evaluating the Ethics of Visual Display 72
three researching technical subjects 73
Primary research: Interviewing 73
Preparing for the interview 74
learn everything you can about the subject 74
learn about the subject matter expert 75
prepare a list of organized questions 75
writing good questions 76
in-class exercise 3.1
Prepare to Interview a Classmate 77
Conducting the interview 77
schedule an hour-long interview, if possible 77
introduce yourself and explain your project 78
decide whether to tape the interview 78
be an active listener 79
control the interview 79
working with those for whom english is a
second language 79
closing the interview 79
in-class exercise 3.2
Interview a Classmate 80
Primary research: Conducting surveys 80
Asking good questions 81
Guidelines for asking good questions 82
rephrase jargon and technical language
into plain language 82
ask specific questions 83
avoid loaded questions 83
break compound questions into individual
questions 83
Choosing appropriate responses 83
Preparing the survey form 85
Reporting survey data 85
major project 3.1
Create a Survey Form 86
Secondary research: Finding print and online sources 87
Conducting an effective search for sources:
Library and Internet 89
Assessing the credibility of your sources 90
Citing and paraphrasing researched sources 92
in-class exercise 3.3
Which Item Needs a Source Cited? 93
in-class exercise 3.4
Which Paraphrase is Legitimate and Which is Too Close to
the Original? 94
Review Copy
 a strategic guide to technical communication
four writing technical prose 95
What is style? 95
Word choice 95
Appropriateness 96
in-class exercise 4.1
Appropriate Word Choices 96
clarity 96
conciseness 97
connotations 97
Sentence composition 98
in-class exercise 4.2
Varying Sentence Length for Greater Impact 98
Sentence structure 98
in-class exercise 4.3
Practising Sentence Variety 100
in-class exercise 4.4
Experimenting with Sentence Variety 101
Figurative language 101
in-class exercise 4.5
Analyse the Rhetorical Effects of Sentence Variety 102
What is figurative language? 102
schemes (changing word order) 102
tropes (changing word meaning) 103
in-class exercise 4.6
Adapting the Simile or Metaphor to the Intended Reader 104
lab assignment 4.1
Using Rhetorical Figures in Your Writing 107
Resources on figurative language 107
Analysing prose 107
Analysing style 108
Sentences 109
Paragraphs 110
Diction (word choice) 111
lab assignment 4.2
Analysing Your Own Prose Style 113
Analysing structure 113
Analysing register 113
Argumentation: Constructing a persuasive case 114
Logos 114
the original claim 116
adding grounds 116
warrants for this claim 116
developing backing for the warrants 117
conditions of rebuttal 118
qualifying our original claim 118
Review Copy
contents 9
in-class exercise 4.7
Developing Evidence to Support a Claim 119
Ethos 119
appear knowledgeable 119
respond fairly to opposing viewpoints 120
establish common ground 120
in-class exercise 4.8
Demonstrating Credibility 120
Pathos (emotional appeal) 120
use examples 121
use word choice, metaphors, and analogies 121
lab assignment 4.3
Constructing a Persuasive Argument 123
Defining, describing, and explaining 123
Definition 124
brief definition 124
formal or categorical definition 125
in-class exercise 4.9
Writing Categorical Definitions 125
extended definition 125
in-class exercise 4.10
Distinguish an Operational Definition from a Set of Instructions 126
lab assignment 4.4
Identifying Methods of Defining, Describing, and Explaining 131
lab assignment 4.5
Defining or Describing a Technical Concept or Device 131
five designing documents and page layout 133
What is document design? 133
in-class exercise 5.1
Evaluating Quality in Document Design 135
What are the elements of document design? 136
Typefaces and fonts 137
should i use a serif or sans-serif font? 137
White space 139
in-class exercise 5.2
Assessing Your Use of White Space 140
Should margins be justified or ragged? 140
Should you use capitals or lower case? 140
Strategic solutions: Four design principles 140
Proximity 141
how do i create proximity? 141
Alignment 142
basic strategies for creating alignment 144
Repetition 144
Review Copy
10 a strategic guide to technical communication
Contrast 145
lab assignment 5.1
Critiquing an Existing Design 146
lab assignment 5.2
Revising a Poor Design 147
major project 5.1
Redesigning a Brochure 147
major project 5.2
Designing a Newsletter 147
Designing a layout grid 148
How do you use the space on your page to
create impact? 149
How do you vary the horizontal or vertical
space on a page? 149
What is a grid? 149
How do I design a grid for my project? 150
What about using a template for my grid design? 151
major project 5.3
Create Your Own Project 152
six writing winning proposals 153
Why write proposals? 153
What kinds of proposals are there? 154
What is a proposal? 155
When should you decline to write a proposal? 156
How do proposals get evaluated? 156
Who is the audience for a proposal? 157
How do you analyse a RFP? 158
Sample RFP analysis 159
What kind of proposal is requested? 159
What are the primary criteria listed in the RFP? 159
in-class exercise 6.1
Analyse an Assignment as an RFP 161
What is persuasion? 162
What are the components of an argument? 162
how do you create a strong logical appeal? 162
how do you appear knowledgeable about
your topic? 164
how do you create an effective emotional
appeal? 168
How do you organize a proposal? 170
lab assignment 6.1
Creating Effective Emotional Appeals 171
What is the standard generic format for a proposal? 171
Questions a proposal must answer 172