Full Description
A Strategic Guide to Technical Communication incorporates useful and specific strategies for writers to create aesthetically appealing and usable technical documentation. These strategies have been developed and tested on a thousand students from a number of different disciplines over twelve years and three institutions. The second edition adds a chapter on business communication, reworks the discussion on technical style, and expands the information on visual communication and ethics into free-standing chapters. Particular attention is paid throughout to the needs of Canadian students.
Contents
PREFACE
ONE THINKING ABOUT AUDIENCE, PURPOSE, AND GENRE
What is technical communication?
How does it differ from other types of writing?
IN-CLASS EXERCISE 1.1
Applying the Communication Triangle to Sample Documents
Creative vs. technical writing
IN-CLASS EXERCISE 1.2
Analysing Documents with Multiple Aims
Who are these "users"?
Ways of thinking about users
IN-CLASS EXERCISE 1.3
Analysing Multiple Audiences for Documents
How do you learn about your users?
Interview users
Observe users
Interview experts
Create user profiles
IN-CLASS EXERCISE 1.4
Write a User Profile
Reaching your primary users
Why are you writing?
LAB ASSIGNMENT 1.1
Characterizing Your Users
What is genre?
LAB ASSIGNMENT 1.2
Linking Purpose and Audience
Structural conventions
Rhetorical conventions
Organization and presentation of content
Goals and function of the genre
Genre and activity sets
What are the main genres of technical communication?
Why does genre matter?
How does one analyse a new genre?
Analysing style
sentences
paragraphs
Analysing structure
Analysing register
diction (word choice)
What are genre sets?
How are the documents in genre sets interdependent?
LAB ASSIGNMENT 1.3
Analysing a New Genre
What are the conventions of the application letter?
What role does the résumé play in this genre set?
MAJOR PROJECT 1.1
The Job Application Package
TWO LEADING AND MISLEADING THE READER: ETHICAL ISSUES OF TECHNICAL COMMUNICATION
Ethics at work
Ethics frameworks
IN-CLASS EXERCISE 2.1
Outlining an Ethical Position
Ethics for students
How is ethics related to technical communication?
Copyright, trademarks, and patents
What is not copyrightable
Rules for copying images
Writing ethically
Plain language guidelines
MAJOR PROJECT 2.1
Ethical Dilemma Paper
THREE RESEARCHING TECHNICAL SUBJECTS
Primary research: Interviewing
Preparing for the interview
learn everything you can about the subject
learn about the subject matter expert
prepare a list of organized questions
writing good questions
IN-CLASS EXERCISE 3.1
Prepare to Interview a Classmate
Conducting the interview
schedule an hour-long interview, if possible
introduce yourself and explain your project
decide whether to record the interview
be an active listener
control the interview
working with those for whom english is a second language
closing the interview
IN-CLASS EXERCISE 3.2
Interview a Classmate
Primary research: Conducting surveys
Asking good questions
Guidelines for asking good questions
rephrase jargon and technical language
into plain language
ask specific questions
avoid loaded questions
break compound questions into individual
questions
Choosing appropriate responses
Preparing the survey form
Reporting survey data
MAJOR PROJECT 3.1
Create a Survey Form
Secondary research: Finding print and online sources
Conducting an effective search for sources: Library and Internet
Assessing the credibility of your sources
Citing and paraphrasing researched sources
IN-CLASS EXERCISE 3.3
Which Item Needs a Source Cited?
IN-CLASS EXERCISE 3.4
Which Paraphrase Is Legitimate and Which Is Too Close to the Original?
FOUR WRITING TECHNICAL PROSE
Clarity
Where do readers look for clues about the writer's main ideas?
place the context or the familiar
information on the left
place main ideas as the subjects of sentences
IN-CLASS EXERCISE 4.1
Place Main Ideas as the Subjects of Sentences
IN-CLASS EXERCISE 4.2
Rewrite a Paragraph from Your Own Prose
locate the subject and the verb close to one another
IN-CLASS EXERCISE 4.3
Position Subjects and Verbs
place important ideas at the end of sentences to emphasize them
place one point in each syntactic structure
place old information that links back in the subject position, and put new information that you want readers to attend to at the point of emphasis
IN-CLASS EXERCISE 4.4
Place Key Ideas in Positions of Emphasis
use verbs rather than nominalizations to express action in your sentences
Cohesion
IN-CLASS EXERCISE 4.5
Locate the Verbs in a Series of Nominalizations
Linking sentences from start to start
Linking sentences from end to start
Additional reading on clarity and cohesion
IN-CLASS EXERCISE 4.6
Create Links between Familiar and New Information
Plain language
IN-CLASS EXERCISE 4.7
Revising for Plain Language #1
Conciseness
Parallelism
IN-CLASS EXERCISE 4.8
Revising for Plain Language #2
Defining, describing, and explaining
Definition
brief definition
formal or categorical definition
IN-CLASS EXERCISE 4.9
Writing Categorical Definitions
extended definition
IN-CLASS EXERCISE 4.10
Distinguish an Operational Definition from a Set of Instructions
LAB ASSIGNMENT 4.1
Identifying Methods of Defining, Describing, and Explaining
LAB ASSIGNMENT 4.2
Defining or Describing a Technical Concept or Device
FIVE DESIGNING DOCUMENTS AND PAGE LAYOUTS
What is document design?
IN-CLASS EXERCISE 5.1
Evaluating Quality in Document Design
What are the elements of document design?
Typefaces and fonts
should i use a serif or sans-serif font?
White space
IN-CLASS EXERCISE 5.2
Assessing Your Use of White Space
Should margins be justified or ragged?
Should you use capitals or lower case?
Strategic solutions: Four design principles
Proximity
how do i create proximity?
Alignment
basic strategies for creating alignment
Repetition
Contrast
Designing a layout grid
LAB ASSIGNMENT 5.1
Critiquing an Existing Design
LAB ASSIGNMENT 5.2
Revising a Poor Design
MAJOR PROJECT 5.1
Redesigning a Brochure
MAJOR PROJECT 5.2
Designing a Newsletter
How do you use the space on your page to create impact?
How do you vary the horizontal or vertical space on a page?
What is a grid?
How do I design a grid for my project?
What about using a template for my grid design?
MAJOR PROJECT 5.3
Create Your Own Project
SIX COMMUNICATING THROUGH VISUALS: VISUAL TECHNICAL COMMUNICATION
Using visuals to communicate effectively
Visual communication and the writing process
What are the "right ways ... to show data"?
Select the right visual for telling that story
pie charts
line graphs
bar charts
dot charts
tables
maps
photographs
line drawings
gantt charts
Use the conventions for typical visuals
a title
a caption
all units labelled
IN-CLASS EXERCISE 6.1
What Does a Gantt Chart Contribute to the Work Schedule?
source of the data
source of visual
Visuals that confuse or mislead
LAB ASSIGNMENT 6.1
Evaluating Visuals
LAB ASSIGNMENT 6.2
Creating Interesting Visuals
LAB ASSIGNMENT 6.3
Evaluating the Ethics of Visual Display
SEVEN WRITING EMAIL AND LETTERS FOR THE WORKPLACE
Essentials of workplace communication
Who are your readers?
power levels, demographics, communication networks, and obstacles to action
What motivates your readers?
Organize and present your ideas to motivate readers to act
IN-CLASS EXERCISE 7.1
Revising to Motivate Readers to Act
Secondary goals for workplace communication
Writing messages: Email, memos, letters
Tips for writing effective email messages
IN-CLASS EXERCISE 7.2
Assessing Subject Lines
writing emails that identify problems
Formatting memos
Formatting memo reports
tips for writing a good memo report
IN-CLASS EXERCISE 7.3
Writing a Solution-Finding Email to Your Instructor
Formatting a business letter
Writing messages
Informative messages
Positive messages
Negative messages
writing a good buffer
IN-CLASS EXERCISE 7.4
Revising a Positive and Informative Message
Persuasive messages
direct request messages
solution-finding messages
IN-CLASS EXERCISE 7.5
Writing a Negative Message
IN-CLASS EXERCISE 7.6
Overcoming Obstacles to Reader Acceptance
IN-CLASS EXERCISE 7.7
Writing a Direct Request Message
EIGHT WRITING WINNING PROPOSALS
Why write proposals?
What kinds of proposals are there?
What is a proposal?
When should you decline to write a proposal?
How do proposals get evaluated?
Who is the audience for a proposal?
How do you analyse a RFP?
Sample RFP analysis
Class proposals: What kind of proposal is requested?
What are the primary criteria listed in the RFP?
IN-CLASS EXERCISE 8.1
Analyse an Assignment as an RFP
What is persuasion?
What are the components of an argument?
how do you create a strong logical appeal?
how do you create a strong ethical appeal?
how do you create an effective emotional appeal?
How do you organize a proposal?
LAB ASSIGNMENT 8.1
Creating Effective Emotional Appeals
What is the standard generic format for a proposal?
questions a proposal must answer
How do you incorporate persuasion into the format to create a winning proposal?
LAB ASSIGNMENT 8.2
Practising Rhetorical Appeals
MAJOR PROJECT 8.1
Writing a Proposal
Option to write a manual
Option to write a recommendation report
NINE REPORTING TECHNICAL INFORMATION
Status or progress reports
Purpose of status report
Content of status report
Writing the status report: Rhetorical considerations
White papers or information reports
LAB ASSIGNMENT 9.1
Writing a Status Report
MAJOR PROJECT 9.1
Reporting Progress on Your Technical Manual
What information do you put in a white paper?
How do you reach the audience for a white paper?
What are some useful strategies that will increase the effectiveness of your white paper?
stand back from your subject matter and summarize the key points that newcomers need to know to appreciate the new product or service
assume your reader is a newcomer to the subject
describe the problem in specific and personalized terms
in describing how your product or service works, distinguish its features from the benefits it confers on the reader
One expert's helpful hint
Usability test your white paper
IN-CLASS EXERCISE 9.1
Converting Product Features to Reader Benefits
MAJOR PROJECT 9.2
Writing a White Paper
LAB ASSIGNMENT 9.2
User Test Your White Paper Draft
The laboratory report
The laboratory notebook
your lab notebook and scientific integrity
how should you organize the information in your notebook?
Writing the laboratory report
format of the lab report
IN-CLASS EXERCISE 9.2
Incorporating Visual Aids into a Lab Report
LAB ASSIGNMENT 9.3
Revising a Lab Report to Improve Its Argument
MAJOR PROJECT 9.3
Writing a Lab Report
Recommendation reports
Report structure
memo or letter of transmittal
title page
executive summary or abstract
recommendations
body of the report
notes, references, appendices
MAJOR PROJECT 9.4
Writing a Recommendation Report
TEN WRITING HOW-TO DOCUMENTS: INSTRUCTIONS, PROCEDURES, AND MANUALS
What makes instructional documents good?
Know your target audience or user group
Include an overview of the procedure
Write usable steps
five strategies for writing readable instructions
IN-CLASS EXERCISE 10.1
Strategies for Writing Good Instructions
IN-CLASS EXERCISE 10.2
Organizing Information for the User
Subdivide the process
how does "chunking" improve the quality of the instructions?
IN-CLASS EXERCISE 10.3
"Chunking" Techniques and Your Target Audience
Use illustrations
visuals in software documentation: use screen shots
LAB ASSIGNMENT 10.1
Creating and Labelling a Screen Shot
how can you make effective use of visuals?
IN-CLASS EXERCISE 10.4
Distinguishing between the Four Methods of Integrating Text and Image
Design an effective page layout
shorten line lengths
choose a page orientation
design a grid to organize your information
include and visually emphasize tips, warnings, and cautions
do usability testing
LAB ASSIGNMENT 10.2
Evaluating Good Instructions—Origami
LAB ASSIGNMENT 10.3
Revising a Poorly Designed Set of Instructions
LAB ASSIGNMENT 10.4
Designing and Writing Instructions on How to Create Screen Shots
MAJOR PROJECT 10.1
Write a Set of Instructions or a Procedure
MAJOR PROJECT 10.2
Write a Technical Manual
ELEVEN TESTING AND REPORTING DOCUMENT USABILITY
What is usability?
Why test for usability?
What is a usability test?
What is the purpose of a usability test?
Planning the test
Selecting test subjects
How many test subjects?
What should you test for?
What should you have users do during the test?
Designing the test
Summarize the purpose of the test
Outline what you want them to do
Thank them for participating
Inform them that they can quit
IN-CLASS EXERCISE 11.1
Modelling Usability Testing
Conducting the test
Demonstrate the equipment
Explain how to "think aloud"
Describe the tasks
Once the test begins, do not talk to your tester
Concluding the test
Reporting your results
The objectives
Target users' level of knowledge
The test subjects
Task assigned to users
What happened during the test
Comments of the users
Plans for revision
Rhetorical challenges of writing a usability report
Analysing your data
Writing the report
evidence for your revision plans
demonstrate your skill and competence
Usability testing is valuable
Design considerations
LAB ASSIGNMENT 11.1
Report on Usability Testing of Your Instructions or Procedure
Acting on your plans for revision
MAJOR PROJECT 11.1
Evaluating the Usability of Your Manual
TWELVE TAKING TECHNICAL COMMUNICATION ONLINE: SHARING DOCUMENTS ELECTRONICALLY AND WRITING ONLINE DOCUMENTS
What is structured documentation?
Converting documents to portable document
file (pdf) format
Sharing documents electronically
How to use rich text format (rtf) files to solve system or program incompatibility
Shared folders and documents posted online
Posting a document file on a web page
update the web page by adding a link to the document
upload the document file and the revised
web page
set page permissions (if necessary)
IN-CLASS EXERCISE 12.1
Posting a Downloadable File on Your Website
Creating an electronic portfolio
what if i don't have a homepage to display my portfolio?
Writing online documents
How do you prepare documents for onscreen use?
page orientation is different
resolution on screen is poorer
don't use blank pages
plan your document navigation
How do you ensure a good visual design?
divide the screen into functional areas
group related items
guide users' eye movements
put action areas near where users will look for them
use consistent design throughout
How do you ensure that your screen display is legible?
be succinct
write for scanability
LAB ASSIGNMENT 12.1
Converting Print to Online Text
use hypertext links to divide long information into multiple pages
name titles and headings effectively
Use standard web-design conventions
what are the conventions?
MAJOR PROJECT 12.1
Preparing Instructional Material for Online Delivery
THIRTEEN PRESENTING TECHNICAL INFORMATION ORALLY
Common speaking occasions
Casual, impromptu, and short talks
Small group meetings
IN-CLASS EXERCISE 13.1
Creating Short Sound Bites
IN-CLASS EXERCISE 13.2
Introducing Yourself
Informal, prepared presentations
IN-CLASS EXERCISE 13.3
Delivering a Short Oral Report
Formal presentations
MAJOR PROJECT 13.1
Creating an Oral Presentation of the Final Course Project
Guidelines for preparing presentations
Decide what information to include in your presentation slides or outline and what to include in a handout
Determine how much background to present early in the presentation
Organize your presentation so that listeners can follow your thoughts
Create visuals to accompany your verbal descriptions
Guidelines for creating slides
Who is your audience?
Brainstorm ideas for slides
Tell a story
Create your slides
Prezi: Overview and zoom
Guidelines for giving presentations
Take advantage of the immediacy of having live human beings in the same room with you
Stand so your audience can see the visuals that you display on the screen
Control the timing of the slides so you control when the presentation moves from one topic to another
Breathe
REFERENCES
INDEX
