A Strategic Guide to Technical Communication

ISBN-13: 9781554811076 / Angielski / Miękka / 2012 / 328 str.

Heather Graves;Roger Graves

Opis

Competitively priced and student-friendly, with a good balance of theoretical material and real-world examples.

Spis treści

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
Analyzing Documents with Multiple Aims
Who are these “users”?
Ways of thinking about users

IN-CLASS EXERCISE 1.3
Analyzing 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 analyze a new genre?

• Analyzing style?
  
  • sentences?
    paragraphs?
• Analyzing structure?
  Analyzing register?
• diction (word choice)

What are genre sets?

• How are the documents in genre sets interdependent?

LAB ASSIGNMENT 1.3
Analyzing 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
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 LAYOUT

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

IN-CLASS EXERCISE 7.5
Writing a Negative Message

IN-CLASS EXERCISE 7.6
Overcoming Obstacles to Reader Acceptance

• direct request messages
  solution-finding messages

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 analyze an 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
Analyze 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
Practicing 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 newcomersneed 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, appendixes

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 Labeling 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
Modeling 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

• Analyzing 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