Technical Communication

John Lannon is Professor Emeritus and former Director of Writing at the University of Massachusetts Dartmouth, where he developed the undergraduate major in professional writing and later co-developed the M.A. program in professional writing. He has also taught at Cape Cod Community College, University of Idaho, Southern Vermont College, and University of Strasbourg. He has authored and coauthored five major textbooks in business communication, rhetoric, and technical communication, book reviews, filmstrips, and environmental documents and instructional software. He is the recipient of an NDEA Fellowship and Fulbright Lectureship. He holds a B.S., M.A. and Ph.D. from the University of Massachusetts Amherst. His initial training and work was in biomedical science and technology with the USAF. He has served as a communications consultant for various companies and government institutions.  He worked seven years in medical laboratories. Laura J. Gurak is professor and founding chair of the Department of Writing Studies at the University of Minnesota. She holds an M.S. in technical communication and a Ph.D. in communication and rhetoric from Rensselaer Polytechnic Institute. She is author of two books from Yale University Press (1997, 2001), the earlier of which was the first book-length work to study online communities and Internet-based social actions. Gurak is also co-editor of several edited collections and author on numerous conference presentations and papers; she is a recipient of the Society for Technical Communication’s Outstanding Article award. Gurak has authored and coauthored five textbooks in technical communication published by Pearson. She has worked as a technical writer and communications consultant for various companies and organizations.

Preface

 

PART 1 COMMUNICATING IN THE WORKPLACE

 

1. INTRODUCTION TO TECHNICAL COMMUNICATION

What Is Technical Communication?

Technical Communication Is a Digital and a Human Activity

Technical Communication Reaches a Global Audience

Technical Communication Is Part of Most Careers

Technical Communicators Play Many Roles 

Main Features of Technical Communication 

Reader-CenteredAccessible and EfficientOften Produced by Teams

Delivered in Paper and Digital Versions

Purposes of Technical Communication

Documents that InformDocuments that Instruct

Documents that Persuade

Preparing Effective Technical Documents

Case Providing Information Readers Can Use

Case Being PersuasiveCase Considering the Ethical Issues

Case Working on Team and Thinking Globally

Projects

 

2. MEETING THE NEEDS OF SPECIFIC AUDIENCES

Analyze Your Document’s Audience and Purpose

Primary and Secondary Audiences

Your Relationship to Your Readers

Purpose of Your Document

Primary and Secondary PurposesIntended Use of the Document

Assess the Audience’s Technical Background

The Highly Technical Audience

The Semitechnical Audience

The Nontechnical Audience

Audiences with Varying Technical Backgrounds

Case Tailoring a Single Document for Multiple Audiences

Web-Based Documents for Multiple Audiences

Identify the Audience’s Cultural Background

Anticipate Your Audience’s Preferences

Length and Details

Format and Medium

ToneDue Date and TimingBudget

Guidelines for Analyzing Your Audience and Its Use of the Document

Develop an Audience and Use Profile

Case Developing an Audience and Use Profile

Check Your Document for Usability

Checklist Usability

Projects

 

3. PERSUADING YOUR AUDIENCE

Identify Your Specific Persuasive Goal

Try to Predict Audience Reaction

Expect Audience Resistance

Know How to Connect with the Audience

Case Connecting with the Audience

Allow for Give-and-Take

Ask for a Specific Response

Never Ask for Too Much

Recognize All Constraints

Organizational Constraints

Legal Constraints

Ethical Constraints

Time Constraints

Social and Psychological Constraints

Consider This People Often React Emotionally to Persuasive Appeals

Support Your Claims Convincingly

Offer Convincing Evidence

Appeal to Common Goals and Values

Consider the Cultural Context

Guidelines for Persuasion

Shaping Your Argument

Checklist Persuasion

Projects

4. WEIGHING THE ETHICAL ISSUES

Recognize Unethical Communication in the Workplace

Know the Major Causes of Unethical Communication

Yielding to Social Pressure

Mistaking Groupthink for Teamwork

Understand the Potential for Communication Abuse

Suppressing Knowledge the Public Needs

Hiding Conflicts of InterestExaggerating Claims about Technology

Falsifying or Fabricating Data

Using Visual Images That Conceal the Truth

Stealing or Divulging Proprietary Information

Misusing Electronic Information

Withholding Information People Need for Their Jobs

Exploiting Cultural Differences

Rely on Critical Thinking for Ethical Decisions

Reasonable Criteria for Ethical Judgment

Ethical Dilemmas

Anticipate Some Hard Choices

Case A Hard Choice

Never Depend Only on Legal Guidelines

Learn to Recognize Plagiarism

Blatant versus Unintentional Plagiarism

Plagiarism and the Internet

Plagiarism and Your Career

Consider This Ethical Standards Are Good for Business

Decide When and How to Report Ethical Abuses

Checklist Ethical Communication

Guidelines for Ethical Communication

Projects

 

5. TEAMWORK AND GLOBAL CONSIDERATIONS

Teamwork and Project Management  

Guidelines for Managing a Collaborative Project

Virtual Meetings

Face-To-Face Meetings

Guidelines for Running a Meeting

Sources of Conflict in Collaborative Groups

Interpersonal Differences

Gender Differences

Cultural Differences

Managing Group Conflict

Overcoming Differences by Active Listening

Guidelines for Active Listening

Thinking Creatively

Brainstorm As a Way of Getting Started

Brainstorming with Digital Technologies

Mind-Mapping

Storyboarding

Reviewing and Editing Others’ Work

Guidelines for Peer Reviewing and Editing

Ethical Abuses in Workplace Collaboration

Intimidating One’s Peers

Claiming Credit for Others’ Work

Hoarding Information

Global Considerations When Working in Teams

 

Interpersonal Issues in Global Teams

Guidelines for Communicating on a Global Team

Checklist Teamwork and Global Considerations

Projects

 

6. AN OVERVIEW OF THE TECHNICAL WRITING PROCESS

Critical Thinking in the Writing Process

A Sample Writing Situation

Working with the Information

Planning the Document

Drafting the Document

Revising the Document

Make Proofreading Your Final Step

Guidelines for Proofreading

Digital Technology and the Writing Process

Checklist Proofreading

Projects

 

PART 2 THE RESEARCH PROCESS

 

7. THINKING CRITICALLY ABOUT THE RESEARCH PROCESS

Asking the Right Questions

Case Defining and Refining a Research Question

Exploring a Balance of Views

Achieving Adequate Depth in Your Search

Evaluating Your Findings

Interpreting Your Findings

Primary versus Secondary Sources

Exploring Secondary Sources

Web-Based Secondary Sources

Locating Secondary Sources Using Google

Locating Secondary Sources Using Wikipedia

Other Web-based Secondary Sources

Guidelines for Researching on the Internet

Traditional Secondary Sources

Exploring Primary Sources

Unsolicited Inquiries

Informational Interviews

Guidelines for Informational Interviews

Surveys

Guidelines for Surveys

Observations and Experiments

Consider This Frequently Asked Questions about Copyright

Projects

 

8. EVALUATING AND INTERPRETING INFORMATION

Evaluate the Sources

Evaluate the Evidence

Interpret Your Findings

Identify Your Level of Certainty

Examine the Underlying Assumptions

Be Alert for Personal Bias

Consider Other Possible Interpretations

Consider This: Standards of Proof Vary for Different Audiences and Cultural Settings

Avoid Distorted or Unethical Reasoning

Faulty Generalization

Faulty Casual Reasoning

Faulty Statistical Analysis

Acknowledge the Limits of Research

Obstacles to Validity and Reliability

Flaws in Research Studies

Deceptive Reporting

Guidelines for Evaluating and Interpreting Information

Checklist The Research Process

Projects

 

9. SUMMARIZING RESEARCH FINDINGS AND OTHER INFORMATION   xx

Considering Audience and Purpose

What Readers Expect from a Summary

Guidelines for Summarizing Information

A Situation Requiring a Summary

Creating a Summary

Special Types of Summaries

Closing Summary

Informative Abstract (“Summary”)

Descriptive Abstract (“Abstract”)

Executive Abstract

Ethical and Global Considerations in Summarizing Information

Checklist Summaries

Projects

 

PART 3 ORGANIZATION, STYLE, AND VISUAL DESIGN

 

10. ORGANIZING FOR READERS

The Typical Shape of Workplace Documents

Outlining

An Outlining Strategy

The Formal Outline

Guidelines for Outlining

Storyboarding

Paragraphing

The Support Paragraph

The Topic Sentence

Paragraph Unity

Paragraph Coherence

Paragraph Length

Chunking

Providing an Overview

Organizing for Global Audiences

Checklist Organizing Information

Projects

 

11. EDITING FOR A PROFESSIONAL STYLE AND TONE

Editing for Clarity

Avoid Ambiguous Pronoun References

Avoid Ambiguous Modifiers

Unstack Modifying Nouns

Arrange Word Order for Coherence and Emphasis

Use Active Voice Whenever Possible

Use Passive Voice Selectively

Avoid Overstuffed Sentences

Editing for Conciseness

Avoid Wordy Phrases

Eliminate Redundancy

Avoid Needless Repetition

Avoid There Sentence Openers

Avoid Some It Sentence Openers

Delete Needless Prefaces

Avoid Weak Verbs

Avoid Excessive Prepositions

Avoid Nominalizations

Make Negatives Positive

Clean Out Clutter Words

Delete Needless Qualifiers

Editing for Fluency

Combine Related Ideas

Vary Sentence Construction and Length

Use Short Sentences for Special Emphasis

Finding the Exact Words

Prefer Simple and Familiar Wording

Avoid Useless Jargon

Use Acronyms Selectively

Avoid Triteness

Avoid Misleading Euphemisms

Avoid Overstatement

Avoid Imprecise Wording

Be Specific and Concrete

Use Analogies to Sharpen the Image

Adjusting Your Tone

Guidelines for Deciding about Tone

Consider Using an Occasional Contraction

Address Readers Directly

Use I and We When Appropriate

Prefer the Active Voice

Emphasize the Positive

Avoid an Overly Informal Tone

Avoid Personal Bias

Avoid Sexist Usage

Guidelines for Nonsexist Usage

Avoid Offensive Usage of All Types

Guidelines for Inoffensive Usage

Considering the Global Context

Legal and Ethical Implications of Word Choice

Style, Tone, and Email   

Using Digital Editing Tools Effectively

Checklist Style

Projects

 

12. DESIGNING VISUAL INFORMATION

Why Visuals Matter

When to Use Visuals

Types of Visuals to Consider

How to Choose the Right Visuals

Tables

Graphs

Bar Graphs

Line Graphs

Guidelines for Creating Tables and Graphs

Charts

Pie Charts

Organization Charts

Flowcharts

Tree Charts

Gantt and PERT Charts

Pictograms

Guidelines for Creating Charts

Graphic Illustrations

Diagrams

Maps

Guidelines for Creating Graphic Illustrations

Photographs

Guidelines for Using Photographs

Videos

Guidelines for Using Videos

Software and Downloadable Images

Using the Software

Using Symbols and Icons

Using Web Sites for Graphics Support

Using Color

Guidelines for Incorporating Color

Ethical Considerations

Present the Real Picture

Present the Complete Picture

Don’t Mistake Distortion for Emphasis

Guidelines for Obtaining and Citing Visual Material

Cultural Considerations

Guidelines for Fitting Visuals with Text

Checklist Visuals

Projects

 

13. DESIGNINGN PAGES AND DOCUMENTS

Page Design in Workplace Documents

How Page Design Transforms a Document

Design Skills Needed in Today’s Workplace

Desktop Publishing

Electronic Publishing

Using Style Sheets and Company Style Guides

Creating a Design that Works for Your Readers

Shaping the Page

Guidelines for Shaping the Page

Styling the Words and Letters

Guidelines for Styling the Words and Letters

Adding Emphasis

Guidelines for Adding Emphasis

Using Headings for Access and Orientation

Guidelines for Using Headings

Audience Considerations in Page Design

Designing Digital Documents

Web Pages

Online Help

Adobe Acrobat and PDF Files

CDs and Other Media

Checklist Page Design

Projects

 

Part 4 Specific Documents And Applications

 

14. MEMOS

Considering Audience and Purpose

Memo Parts and Format

Memo Tone

Common Types of Memos

Transmittal Memo

Summary or Follow-up Memo

Routine Miscellaneous Memo

Guidelines for Memos

Checklist Memos

Projects

 

15. EMAIL AND TEXT MESSAGING

Email Parts and Format

Considering Audience and Purpose

Email Style, Tone, and Etiquette

Interpersonal Issues and Email

Using the Right Tool for the Situation

Using Visuals with Email

Ethical and Legal Issues When Using Email

Copyright Issues

Privacy Issues

Global Considerations When Using Email

Guidelines for Writing and Using Email

Guidelines for Choosing Email Versus Paper, Telephone, or Fax

Text Messaging

Guidelines for Text Messaging

Checklist Email and Text Messages

Projects

 

16. WORKPLACE LETTERS

Considering Audience and Purpose

Letter Parts, Format, and Design Elements

Standard Parts

Optional Parts

Formats and Design Features

Letter Tone

Establish and Maintain a “You” Perspective

Be Polite and Tactful

Use Plain English

Decide on a Direct or Indirect Organizing Pattern

Global and Ethical Considerations

Guidelines for Letters in General

Conveying Bad or Unwelcome News

Guidelines for Conveying Bad News

Common Types of Letters

Inquiry Letters

Guidelines for Inquiry Letters

Claim Letters

Guidelines for Claim Letters

Sales Letters

Guidelines for Sales Letters

Adjustment Letters

Guidelines for Adjustment Letters

Checklist Letters

Projects

 

17. RÉSUMÈS AND OTHER JOB-SEARCH MATERIALS

Assessing Your Skills and Aptitudes

Researching the Job Market

Plan Your Strategy

Focus Your Search

Explore Online Resources

Learn to Network

Résumés

Parts of a Résumé

Résumés from a Template

Organizing Your Résumé

Guidelines for Hard-Copy Résumés

Electronic Résumés

Guidelines for Emailed and Scannable Résumés

Guidelines for Online Résumés

Application Letters

Solicited Application Letters

Unsolicited Application Letters

Guidelines for Application Letters

Consider This How Applicants Are Screened for Personal Qualities

Dossiers, Portfolios, and Webfolios

Dossiers

Portfolios and Webfolios

Guidelines for Dossiers, Portfolios, and Webfolios

Interviews and Follow-Up Letters

Interviews

Follow-Up Letters

Guidelines for Interviews and Follow-Up Letters

Checklist Résumés

Checklist Application Letters

Checklist Supporting Materials

Projects

 

18. TECHNICAL DEFINITIONS

Considering Audience and Purpose

Legal, Ethical, Societal, and Global Implications

Types of Definition

Parenthetical Definitions

Sentence Definitions

Expanded Definitions

Methods for Expanding Definitions

Etymology

History

Negation

Operating Principle

Analysis of Parts

Visuals

Comparison and Contrast

Required Conditions

Examples

Situations Requiring Definitions

An Expanded Definition for Semitechnical Readers

An Expanded Definition for Nontechnical Readers

Placing Definitions in a Document

Guidelines for Definitions

Checklist Definitions

Projects

 

19. TECHNICAL DESCRIPTIONS, SPECIFICATIONS, AND MARKETING MATERIALS

Considering Audience and Purpose

Types of Technical Descriptions

Objectivity in Technical Descriptions

Elements of a Usable Description

Clear and Limiting Title

Appropriate Level of Detail and Technicality

Visuals

Clearest Descriptive Sequence

An Outline for Product Description

A Situation Requiring Product Description

A Mechanism Description for a Nontechnical Audience

An Outline for Process Description

A Situation Requiring Process Description

A Process Description for a Nontechnical Audience

Guidelines for Descriptions

Specifications

Types of Specifications

Considering Audience and Purpose

Guidelines for Specifications

Technical Marketing Materials

Guidelines for Technical Marketing Materials

Checklist Technical Descriptions

Checklist Specifications

Checklist Technical Marketing Materials

Projects

 

20. INSTRUCTIONS AND PROCEDURES

Considering Audience and Purpose

Formats for Instructional Documents

Faulty Instructions and Legal Liability

Elements of Effective Instructions

Clear and Limiting Title

Informed Content

Visuals

Appropriate Level of Detail and Technicality

Guidelines for Providing Appropriate Detail

Logically Ordered Steps

Notes and Hazard Notices

Readability

Effective Design

Guidelines for Designing Instructions

An Outline for Instructions

Introduction

Body: Required Steps

Conclusion

A Situation Requiring Instructions

A Complete Set of Instructions for a Nontechnical Audience

Digital and Online Instructions

Video Instructions

Scripting Online Videos

Procedures

Evaluating the Usability of Instructions and Procedures

Usability and the Goals of Your Readers

Approaches for Evaluating a Document’s Usability

Checklist Instructions and Procedures

Projects

 

21. INFORMAL REPORTS

Informational versus Analytical Reports

Progress Reports

Guidelines for Progress Reports

Periodic Activity Reports

Guidelines for Periodic Activity Reports

Trip Reports

Guidelines for Trip Reports

Meeting Minutes

Guidelines for Meeting Minutes

Feasibility Reports

Guidelines for Feasibility Reports

Recommendation Reports

Guidelines for Recommendation Reports

Justification Reports

Guidelines for Justification Reports

Peer Review Reports

Guidelines for Peer Review Reports

Checklist Informal Reports

Projects

 

22. FORMAL ANALYTICAL REPORTS

Considering Audience and Purpose

Typical Analytical Problems

Causal Analysis: “Why Does X Happen?”

Case The Reasoning Process in Causal Analysis

Comparative Analysis: “Is X or Y Better for Our Needs?”

Case The Reasoning Process in Comparative Analysis

Feasibility Analysis: “Is This a Good Idea?”

Case The Reasoning Process in Feasibility Analysis

Combining Types of Analysis

Elements of an Effective Analysis

Clearly Identified Problem or Purpose

Adequate But Not Excessive Data

Accurate and Balanced Data

Fully Interpreted Data

Subordination of Personal Bias

Appropriate Visuals

Valid Conclusions and Recommendations

Self-Assessment

An Outline and Model for Analytical Reports

Introduction

Body

Conclusion

Front Matter and End Matter Supplements

Front Matter

Letter of Transmittal

Text of the Report

End Matter

A Situation Requiring an Analytical Report

A Formal Report

Guidelines for Reasoning through an Analytical Problem

Checklist Analytical Reports

Projects

 

23. PROPOSALS  

Considering Audience and Purpose

The Proposal Process

Case Submitting a Competitive Proposal

Types of Proposals

Planning Proposals

Research Proposals

Sales Proposals

Elements of a Persuasive Proposal

A Forecasting Title or Subject Line

Background Information

Statement of the Problem

Description of Solution

A Clear Focus on Benefits

Honest and Supportable Claims

Appropriate Detail

Readability

A Tone That Connects with Readers

Visuals

Accessible Page Design

Supplements Tailored for a Diverse Audience

Proper Citations of Sources and Contributors

An Outline and Model for Proposals

Introduction

Body

Conclusion

Guidelines for Proposals

A Situation Requiring a Formal Proposal

A Formal Proposal

Checklist Proposals

Projects

 

24. ORAL PRESENTATIONS AND WEBINARS

Advantages and Drawbacks of Oral Presentations

Avoiding Presentation Pitfalls

Planning Your Presentation

Analyze Your Audience and Purpose

Analyze Your Speaking Situation

Select a Type of Presentation

Select a Delivery Method

Preparing Your Presentation

Research Your Topic

Aim for Simplicity and Conciseness

Anticipate Audience Questions

Outline Your Presentation

Planning and Creating Your Visuals

Decide Which Visuals to Use and Where to Use Them

Create a Storyboard

Decide Which Visuals You Can Realistically Create

Prepare Your Visuals

Guidelines for Readable and Understandable Visuals

Choosing the Right Visual Medium

Using Presentation Software

Ethics and the Use of Presentation Software

Case  PowerPoint and the Space Shuttle Columbia Disaster

Guidelines for Using Presentation Software

Delivering Your Presentation

Rehearse Your Delivery

Check the Room and Setting Beforehand

Cultivate the Human Landscape

Keep Your Listeners Oriented

Plan for How You Will Use Any Non-Computer Visual Aids

Guidelines for Presenting Visuals

Manage Your Presentation Style

Manage Your Speaking Situation

Guidelines for Managing Listener Questions

Guidelines for Delivering Oral Presentations

Consider This Cross-Cultural Audiences May Have Specific Expectations

Webinars and Distance Presentations

Webinars

Slide Sharing and Other Tools

Guidelines for Webinars and Distance Presentations

Checklist Oral Presentations

Projects

 

25. WEB PAGES

Considering Audience and Purpose

How People Read Web Pages

Writing for the Web

Guidelines for Writing Web Pages

Designing Web Pages

Guidelines for Designing Web Pages

Techniques and Technologies for Creating Web Sites

Planning Web Sites Using Storyboarding

Teamwork When Creating Web Sites

Creating Web Pages Using Word Processing and Other Software

Global Issues and Web Pages

Guidelines for Addressing Global Audiences

Ethical and Legal Considerations

Ethical Considerations

Legal Considerations

Checklist Writing and Designing Web Pages

Projects

 

26. SOCIAL MEDIA

Considering Audience and Purpose

   Audience As Contributor

Using Social Media for Technical Communication

   Blogs

   Wikis

Guidelines for Writing and Using Blogs and Wikis

   Social Networking Sites

   Job and Professional Networking Sites

Guidelines for Writing and Using Social Networks

   Customer Review Sites

   Twitter Feeds  

Ethical and Legal Considerations

Checklist: Social Media

Projects

 

PART 5 RESOURCES FOR TECHNICAL WRITERS 675



APPENDIX A: A QUICK GUIDE TO DOCUMENTATION

Taking Notes

Guidelines for Recording Research Findings

Quoting the Work of Others

Guidelines for Quoting the Work of Others

Paraphrasing the Work of Others

Guidelines for Paraphrasing

What You Should Document

How You Should Document

MLA Documentation Style

MLA Parenthetical References

MLA Works Cited Entries

MLA Sample Works Cited Pages

APA Documentation Style

APA Parenthetical References

APA Reference List Entries

APA Sample Reference List

CSE and Other Numbered Documentation Styles

CSE In-Text Citations

CSE Reference List Entries



APPENDIX B: A QUICK GUIDE TO GRAMMAR, USAGE, AND MECHANICS

Grammar

Sentence Fragments

Run-On Sentences

Comma Splices

Faulty Agreement–Subject and Verb

Faulty Agreement–Pronoun and Referent

Dangling and Misplaced Modifiers

Faulty Parallelism

Faulty Coordination

Faulty Subordination

Faulty Pronoun Case

Punctuation

Period

Question Mark

Exclamation Point

Semicolon

Colon

Comma

Apostrophe

Quotation Marks

Ellipses

Brackets

Italics

Parentheses

Dashes

Mechanics

Abbreviation

Hyphenation

Capitalization

Numbers and Numerals

Spelling

Usage

Transitions

Use Transitional Expressions

Repeat Key Words and Phrases

Use Forecasting Statements

Lists

Embedded Lists

Vertical Lists

 

Works Cited

Index