A Strategic Guide to Technical Communication, second edition

Table of 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 in-class exercise 1.2 Analysing Documents with Multiple Aims Creative vs. technical writing 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 lab assignment 1.1 Characterizing Your Users Reaching your primary users Why are you writing? lab assignment 1.2 Linking Purpose and Audience What is genre? 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) lab assignment 1.3 Analysing a New Genre What are genre sets? How are the documents in genre sets interdependent? 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 in-class exercise 3.3 Which Item Needs a Source Cited? Citing and paraphrasing researched sources 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 in-class exercise 4.4 Place Key Ideas in Positions of Emphasis 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 USE VERBS RATHER THAN NOMINALIZATIONS TO EXPRESS ACTION IN YOUR SENTENCES in-class exercise 4.5 Locate the Verbs in a Series of Nominalizations Cohesion Linking sentences from start to start Linking sentences from end to start in-class exercise 4.6 Create Links between Familiar and New Information Additional reading on clarity and cohesion Plain language in-class exercise 4.7 Revising for Plain Language #1 in-class exercise 4.8 Revising for Plain Language #2 Conciseness Parallelism Defining, describing, and explaining Definition BRIEF DEFINITION FORMAL OR CATEGORICAL DEFINITION in-class exercise 4.9 Writing Categorical Definitions in-class exercise 4.10 Distinguish an Operational Definition from a Set of Instructions EXTENDED DEFINITION 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 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 Designing a layout grid 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 in-class exercise 6.1 What Does a Gantt Chart Contribute to the Work Schedule? Use the conventions for typical visuals A TITLE A CAPTION ALL UNITS LABELLED 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 in-class exercise 7.3 Writing a Solution-Finding Email to Your Instructor Formatting memos Formatting memo reports TIPS FOR WRITING A GOOD MEMO REPORT Formatting a business letter Writing messages Informative messages Positive messages in-class exercise 7.4 Revising a Positive and Informative Message Negative messages WRITING A GOOD BUFFER in-class exercise 7.5 Writing a Negative Message Persuasive messages DIRECT REQUEST MESSAGES in-class exercise 7.6 Overcoming Obstacles to Reader Acceptance in-class exercise 7.7 Writing a Direct Request Message SOLUTION-FINDING MESSAGES 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? lab assignment 8.1 Creating Effective Emotional Appeals How do you organize a proposal? 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 lab assignment 9.1 Writing a Status Report major project 9.1 Reporting Progress on Your Technical Manual White papers or information reports 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 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 One expert’s helpful hint Usability test your white paper 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 Yorself 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