1. The Golden Rules Technical communication theory and application TCUK 2012 Leah Guren Cow TC

2. Meet the Golden Rules. Why theory? tool agnostic works for all types of TC projects provides a practical methodology Why these particular elements (the GoldenRules)? the most common and critical based on experience and research People read books, but they use documentation. 3. The TC is a translator. 4. #1: Paper is permanent. 5. Hight protein powder provides the correct balance ofamnio acids to supplement the vagetarian/vegan dietor the of anyone who is lactose intolerant. Over 80%protein suger freee no added salat.Over 200 medical jouranls documented as effective infighting and prevent: cancer, heartdisease, diabetes, diarrhea and moor.Monufachured: numary drive sheffield England 6. supports pear-to-pearnetworking based on pubic domain protocols.5. Click Advanced to defile system parameters. 7. What are quality and usability? Quality is a measure of accuracy (absence oferrors): typos, spelling mistakes, punctuation mistakes incorrect data Usability is a measure of how easily a documentcan be used: can users find the information? can they understand it and use it? remember: a doc may have no errors but still not beusable! Good docs need quality and usability! 8. You must be an expert. As a professional writer, you are expected toknow this. You may not have access to an editor. If you never learned, invest the time ASAP: grammar (including all that annoying jargon) punctuation proper writing style for TC 9. Parsing depends on punctuation.woman without her man is nothingWoman without her man is nothing.Woman: without her, man is nothing.9 10. Review TC punctuation rules. Commas closed (aka serial or Oxford comma) nonrestrictive phrases after prepositional phrases Colons and semicolons colons introduce semicolons link independent clauses never allow a comma splice Apostrophes contractions are OK dont use with acronym plurals 11. Review TC punctuation rules, cont. Quotation marks never quote product or feature names, interfaceelements, or actions (typeset instead) use correct symbols (printers quotation marks, notstraight ASCII quotes) Dashes distinguish hyphens, en dashes, and em dashes be consistent with space usage Parentheses nested vs. stand-alone parentheticals Capitalization dont capitalize things not labels or proper nouns 12. Punctuation can add tone. Keep all files, including sample data, in the same folder. Keep all files (including sample data) in the same folder. Keep all filesincluding sample datain the same folder. 13. Review TC writing style rules. Active voice Simple present tense Short sentences Simple, direct language Factual and accurate Unambiguous (watch those modifiers!) No gender bias 14. Paper is permanent. It is your responsibility to proofread and editcarefully. If the docs have sloppy mistakes and lookunprofessional, users dont trust the info. If the docs are ambiguous, hard to understand, orincomplete (poor usability), users turn to techsupport (costing your company more $ ). Exercise 1: Proofread. 15. #2: Know your audience. 16. You need Administrative Privileges toinstall the hub software....3. To change the value, position the mouse cursor over the username and click (press once) with the right mouse button. 17. Know your audience. Map demographics. Consider technical and product knowledge. Make safe assumptions. Distinguish the user from the market. Identify special needs. Find ways to get this info: tap internal sources (marketing, tech support, etc.) get customer contact Create personas. Exercise 2: Identify audience problems. 18. Whats the problem? Why? What is a better solution? 19. #3: Highlight hazards. 20. Cleaning the FryerClean the unit before storing or, during frequent use,every week.1. Open the unit by turning the lock nuts to the horizontal position.2. Lift the basket from the unit and place on newspaper or rags to drain... 21. CAUTION! INVISIBLE LASER RADIATION WHEN OPEN. AVOID EXPOSURE TO BEAM. 22. Highlight hazards. Find hidden hazards through scenarios. Rank hazards by severity: Danger Warning or Caution Note Make hazard visually clear. Use a simple do/do not statement. Explain ramifications and work-arounds. Place hazards appropriately: not after not too far before 23. Sample Hazard Note: The unit may reach high temperatures. Care should be taken to avoid contact with internal elements until the unit has achieved sufficient thermo-adjustment. DO NOT open the unit for at least ten (10) minutes. Allow the unit to cool down; high internal temperatures may cause burns. Caution Exercise 3: Spot the hazards. 24. What are the problems? How do you know? What are two possible ways of dealing withstep 3? 25. #4: Break it out. 26. Antihistimine ComparisonAllegra (Fexofenadine; Aventis) is prescription only.Allegra D is basically Allegra plus a decongestant in acombination tablet (Aventis). Clarinex (Desloratadine;Schering-Plough) is prescription only. However, Claritin(Loratidine; Schering-Plough) became available as anover-the-counter drug in December of 2002. Claritin D isClaritin with a decongestant in a combination tablet(Schering-Plough). 27. First, sort the clothing by color and fabric weight. Next,go through all garments carefully to empty pockets.Also look for any loose buttons that may come off inthe wash. Then, make sure that you read the carelabels for washing instructions, especially for any newgarments that you havent already laundered. Now,find any stains or heavily soiled areas (check collars,cuffs, etc.) and pre-treat them according to theinstructions on the stain remover product. Then, startthe wash, making sure to use the right temperature forthe clothes. In general, light colors and sturdy fabrics(such as cotton) can take hotter temperatures. 28. Break it out and provide structure. Users dont read blocks of text! Provide structure in documents. Think visually. Think about the way people need information. Exercise 4: Add structure. 29. What would you recommend for: Two older friends who are real foodies An amateur photographer with a very limitedamount of vacation time Newlyweds (wife is a wheelchair athlete) A vegetarian adventure traveler 30. #5: Dont write blind. 31. We are supplying a software patch which shouldtake care of your Registry corruption problem.After you install the patch (copy the files to theinstallation directory), reset access value to singlecopy. Since you are running an old version(Windows 95 with French support), change thekeyboard setting for the proper ASCII code page.This is in the Control Panel. The next time yourun the software, you will see the new accesscheck-box in the Configuration dialog box. Usethis (default) with single copy settings. 32. Background FilterIf selected, background filtering is allowed. 33. Know what youre writing. Never rely on second-hand information. See it, touch it, use it. If you cant do it, you cant explain it. Think and ask (open questions and scenarios):what the client wants is not always what usersneed . Exercise 5: Think and ask. 34. These should have made you suspicious: Why all the blah-blah in the beginning? Based on the audience, isnt the hazard wrong? How can this end after 16 weeks? What are the blue weights? Included? Show the exercises. Why a print document? Isthis the best way to train people? What is the problem with cold water? 35. #6: Be consistent. 36. The flexible baseboard design willaccept Pentium processors operating at75 MHz, 90MHz, 100 MHz, 120MHz, 133 mhz, 150-Mhz, and 166 MHz. 37. Be consistent. Inconsistency is very stressful for the user. Decide how to refer to the product. Pick one technical term. Consider interface elements and actions. Dont forget styles, fonts, and layout. Use a style guide. Exercise 6: Spot the inconsistencies. 38. Inconsistencies: Product name written several different ways Prereqs dont list quantities for all Units of measurement mix imperial and metric Technical terms: spray watering, sprinkler delivery faucet, tap drip irrigation, tube irrigation 39. #7: Signpost! 40. 1. Complete the software installation before installing the fax-modem card.2. If the default jumper settings are not appropriate, change them before installing the card.3. After installing the card, reboot the PC and run Quickcnf.exe from the Dialer folder... 41. Signpost CLI: If it isnt documented, it doesnt exist. GUI: If it isnt accessible, it isnt documented. Never make users read material that isntappropriate for them. Use layout and typography to indicaterelationships of elements. All parts of the documentation suite need tobe aware of each other. 42. #8: Dont violate standards. 43. Attach the cable to the wide connection plug at theback of the box. 44. Dont violate (legitimate) standards. Recognize the difference between a legitimate(de jure) standard and a bad de facto rule. Understand issues relating to: regulatory and compliance certification recommendations other legal issues Go to the source for certification and guidelinestandards. Get in the loop. Exercise 7: Conduct a standards audit. 45. What did you discover? Are you missing info? How can you resolve this? 46. #9: Contemplate before you illustrate. 47. 4. To determine the card version, refer to the serial number printed on the main chip. 48. Contemplate before you illustrate. Consider when you must have graphics: non-text GUI elements physical parts and assembly orientation (perfuming the pig) You may not need all of it. You may not need it at all! Use appropriate graphic types. Use callouts or annotations to focus attention. Placed the graphic after concept. 49. inline graphicof non-textGUI elementannotatedscreen grab 50. drawing with elementslabeled (text overlaid ongraphic)Note: Avoid forlocalizationstrategy! 51. explodedviewdiagram 52. isometric viewdiagram 53. drawing with callouthandlesExercise 8: What is essential? 54. Did you have an icon for the battery symbol? Did you use a cabinet or isometric view? Did you remember the annotations? 55. #10: Cut the fluff. 56. We have included a free registration card with so that you can fill it out andmail it back to us as quickly as possible (weveeven paid for the postage, youll note). We couldtake up several precious minutes of your lifetelling you why this is a good idea, but we wont. 57. The potential for attendance at the aforementionedconference is problematic in that it is difficult, if notimpossible, to anticipate to any degree of certainty thenumber of persons who will participate until very close tothe actual target date. This being so, it is thereforedesirable that detailed planning be based on anassumption of capacity seating at most sessions withinthe event; that is, planning and prearranging should bedone so that all last-minute changes are downwardadjustments in nature. 58. Cut the fluff. Fluff is a serious usability problem. Watch out for these common fluff items: formal and pompous writing hidden strong verbs unnecessary passive voice Vague language is also fluff. Where possible, use telegraphic style. Think visually to reduce text. KISS! Exercise 9: Cut the fluff. 59. Conclusion and Discussion The Golden Rules: provide the analytical decision tree for all projects help you defend editorial choices support a user-centric approach to documentation Where do you go from here? consider new trends and technologies in terms of GRusability dont ever forget your TC role as translator 60. Thank you!Leah GurenA buttertechnical communicationapproach totraining & consultingTCtel: (+972) 54-485-3473email: leah@cowtc.comSkype: leah.gurenwebsite: www.cowtc.com