Technical Style Workshop Part 2


Published on

The second part of a 2-part introductory workshop on style in technical communication. Presented December 8, 2009 to beginning technical writing students at Kyung Hee University in Suwon, South Korea.

Published in: Business, Technology

Technical Style Workshop Part 2

  1. 1. Technical Style<br />A 2-day workshop presented by Edwin Hollon<br />December 1 & 8, 2009<br />Kyung Hee University – Suwon, South Korea<br />
  2. 2. Accuracy<br />Accuracy can mean the difference between success and failure in technical documentation.<br />Non-specific language can lead to misunderstandings (best case) or create dangerous or deadly situations for readers/users (worst case).<br />Accuracy is often subjective (level of accuracy depends on whether or not your language is understood by the audience).<br />
  3. 3. Accuracy<br />Principle 7: Avoid unnecessary jargonand language that is unfamiliar or unknown to your audience.<br />Jargon –language used by a specific group that holds particular meaning for that group (often technical, but not necessarily suitable for general audiences)<br />Bilateral probital hematoma<br />Slang – informal, invented, arbitrary, or extravagant language (not technical)<br /> black eye, shiner<br />Use language that fits the rhetorical situation<br />
  4. 4. Exercise 7<br />What are some situations where jargon can be useful? Match the type of language to the situation.<br />Doctor to a patient<br />Doctor to other medical professionals at a conference.<br />Pilot to the control tower.<br />Pilot to passengers.<br />The patient has a distal radius fracture. / The patient has a broken arm<br />We will be landing shortly. / We are making a thirty degree southeasterly approach.<br />Notice how jargon can be used to transfer very specific information to the audience.<br />
  5. 5. Accuracy<br />Principle 8: Avoid using too many hedges and intensifiers.<br />Hedges – describe uncertainty or show caution<br />Adverbs: usually, often, sometimes, almost, possibly, perhaps<br />Adjectives: most, many, some, a certain number of<br />Verbs: may, might, can, could, seem, tend appear, suggest<br />There seems to be some evidence to suggest that certain differences between Japanese and Western rhetoric could derive from historical influences possibly traceable to Japan’s cultural isolation and Europe’s history of cross-cultural contacts.<br />Be specific and confident in your writing.<br />
  6. 6. Accuracy<br />Principle 8: Avoid using too many hedges and intensifiers.<br />Intensifiers – show assertiveness, but can be overly confident or even inaccurate<br />Adverbs: very, pretty, quite, rather, clearly, obviously, certainly<br />Adjectives: key, central, crucial, basic, fundamental, major<br />Verbs: show, prove, establish, as you can see, it is clear<br />For a century now, all liberals have argued against any censorship of art, and every court has found their arguments so completely persuasive that not a person any longer remembers the opposing arguments.<br />Don’t be overly aggressive in your writing.<br />
  7. 7. Exercise 8<br />What are the hedges and intensifiers in these sentences? How can you make the sentences clearer?<br />On the other hand, we can perhaps point out that there may always be TV programming that appeals to our lowest interests.<br />On the other hand, TV programming often appeals to our lowest interests.<br />The extremely terrible storm ripped across the bay and totally destroyed business buildings and homes when it hit shore. The result was very disastrous: so much wreckage, so many helpless people, so many lost dreams. To see it was really disturbing.<br />The terrible storm ripped across the bay and destroyed business buildings and homes when it hit shore. The result was disastrous: wreckage, helpless people, lost dreams. To see it was disturbing.<br />
  8. 8. Accuracy<br />Principle 9: Avoid noun stacks.<br />Noun stack – three or more nouns in a row; common in technical terminology<br />information processing behavior<br />computer human cognition simulation<br />Long strings of nouns can be difficult for readers to “unpack.”<br />Translating noun stacks can be difficult or, in some cases, impossible.<br />Noun stacks often include nominalizations.<br />Unpack noun stacks by inserting prepositions and articles and eliminating nominalizations.<br />
  9. 9. Exercise 9<br />What are the noun stacks in these sentences? How can they be rewritten?<br />The plant safety standards committee discussed recent air quality regulation announcements.<br />The committee that is responsible for safety standards in the plant discussed the recent announcements about regulations regarding air quality.<br />Enforcement of guidelines for new automobile tire durability must be a Federal Trade Commission responsibility.<br />The Federal Trade Commission must be responsible for enforcing guidelines to ensure the durability of tires on new automobiles.<br />
  10. 10. Review: Accuracy<br />Jargon affects accuracy if the audience is unfamiliar with the terminology you use.<br />Technical jargon can either exclude or include readers<br />Slang is almost always inappropriate for technical documentation<br />Use the terminology that best fits the rhetorical situation<br />Unnecessary hedges and intensifiers can weaken technical documentation.<br />Hedges can show caution or lack of confidence<br />Intensifiers can be too aggressive and may be inaccurate<br />To make your writing accurate, write confidently but don’t exaggerate or make false claims<br />Noun stacks can hide your intended meaning<br />Three or more nouns in combination is a noun stack<br />Noun stacks put a burden on the reader and are often difficult to translate<br />Unpack noun stacks by using prepositions and articles; eliminate nominalizations<br />
  11. 11. Break<br />15 minutes<br />
  12. 12. Negative vs. Positive Language<br />Principle 10: Change negatives into affirmatives.<br />When you use negative language, readers must mentally convert the language to understand what they should do. Negative language also requires extra words in many cases:<br />same  not different<br />Negative language often describes the opposite of the action you want your audience to perform:<br />Do not write in the negative.  Write in the affirmative.<br />Tell your readers exactly what they should do by using positive (affirmative) language.<br />
  13. 13. Exercise 10<br />How can these expressions be changed from negative to affirmative?<br />not different <br />not the same <br />not allow <br />not many <br />not often <br />not stop <br />similar<br />different<br />prevent<br />few<br />rarely<br />continue<br />
  14. 14. Negative vs. Positive Language<br />Some verbs, prepositions, and conjunctions describe negative situations.<br />Verbs: preclude, prevent, lack, fail, doubt, reject, avoid, deny, refuse, exclude, contradict, prohibit, bar<br />Prepositions: without, against, lacking, but for, except<br />Conjunctions: unless, except when<br />When you combine one of these words with not, readers can easily misunderstand your intended meaning.<br />Except when applicants have failed to submit applications without documentation, benefits will not be denied.<br />You will receive benefits only if you submit your documents.<br />
  15. 15. Exercise 11<br />First, eliminate the nominalizations and passive voice. Then, change the negatives into affirmatives.<br />There should be no submission of payments without notification of this office, unless the payment does not exceed $100.<br />Do not submit payments if you have not notified this office, unless you are paying $100.<br />If you pay more than $100, notify this office first.<br />
  16. 16. Commonly Misused Words<br />All writers make usage mistakes from time to time. Mistake in usage occur for different reasons:<br />Homonyms<br />they’re, their, there<br />it’s, its<br />Misunderstood meanings<br />discrete vs discreet<br />contiguous, continual, continuous<br />Different meanings in different contexts or languages (slang or invented definitions)<br />ride<br />chill<br />Commonly misspelled or unintended usage<br />lose vs loose<br />past vs passed<br />
  17. 17. Exercise 12<br />Choose the correct word to complete the sentence (complete the exercise in your workbook).<br />Loose or Lose?<br />Do not _______ the money Sarah gave you.<br />Someone needs to catch that ______ dog.<br />Put the _______ papers in your notebook.<br />Did the Bulldogs _______ by many points?<br />Affect or Effect?<br />How did that last test ________ your grade in history?<br />Regular study habits usually have a positive _______ on a grade.<br />Accept or Except?<br />I will _______ all of your terms.<br />Everyone _______ Adam will be able to come to the meeting.<br />He will go to the ceremony to _______ the award.<br />
  18. 18. Commonly Misused Words<br />Q: How do I (ensure/assure/insure) that I use the appropriate word in my writing?<br />A: Use a style guide<br />
  19. 19. Style Guides<br />Style guides improve accuracy and consistency.<br />A style guide can help multiple writers who are creating numerous documents use the same voice.<br />Style guides define terms, rules, occasions for use, and exceptions.<br />Style guides represent the common language and culture of a company, industry, or group.<br />They can also describe document layouts, proper use of design elements, and official guidelines for representing company brands and trademarks.<br />Many global organizations create image guidelines to dictate how their product and brand names should be used by company personnel, subcontractors, partners, and the media.<br />
  20. 20. Style Guides<br />Types of style guides:<br />General – general guides cover basic grammar rules for common types of writing, such as creating college essays.<br />The Elements of Style (Strunk and White)<br />A Writer’s Reference (Diana Hacker)<br />Domain-specific – style guides developed for particular domains help writers (and readers) speak a common language and conform their writing to academic or industry guidelines.<br />The Chicago Manual of Style (journalism)<br />Publication Manual of the American Psychological Association (psychology and other medical fields)<br />
  21. 21. Style Guides<br />Types of style guides:<br />Company-specific – a company’s style guide helps authors create a consistent look and feel for the company’s documents. This type of style guide helps authors reinforce the company’s image and brand names.<br />Google, Apple, Microsoft, etc.<br />Some are adopted as domain-specific guides, such as Read Me First! (Sun Microsystems) or The Microsoft Manual of Style<br />Custom – custom guides can be created for any application, such as a particular project.<br />
  22. 22. Exercise 13<br />Which types of style guides might you use in the following situations?(general, domain-specific, company-specific, or custom?)<br />Writing marketing documents for a new product line.<br />Writing user guidance for consumer electronics.<br />Writing a master’s thesis.<br />Writing error messages for a software program.<br />Writing a proposal to build a new museum.<br /><ul><li>Use general guides for main grammar rules.
  23. 23. Use domain-specific guides for industry conventions.
  24. 24. Create company-specific or custom guides for projects, customers, product lines, etc.</li></li></ul><li>Exercise 14<br />Which style choices would you make?<br />Spelling:<br />Email, email, e-mail, E-mail, emails<br />Internet, internet, Web, web, worldwide web<br />online, on line, on-line<br />Usage:<br />push, press<br />turn, rotate, twist, spin<br />Terminology:<br />latch, hook, fastener<br />handphone, mobile phone, cell phone, phone, product, device <br />
  25. 25. Review: Style Guides<br />Style guides help authors:<br />Write accurately<br />Write consistently<br />Meet audience expectations (terms, presentation formats)<br />Meet organizational goals (branding)<br />Style guides come in various forms: General, Domain-specific, Customer-specific, and Custom<br />In many situations, authors may use multiple style guides in combination.<br />You can easily make your own custom style guide by recording your decisions about spelling, usage, terminology, and design.<br />
  26. 26. Tools & Reference Materials<br />I highly recommend these tools for learning and writing in English. They are very useful for non-native English speakers and can be used in a wide range of situations—from college writing to technical communication.<br />Cambridge Learner’s Dictionary (2nd Edition) – Cambridge University Press<br />Cambridge Advanced Learner’s Dictionary (3rd Edition) – Cambridge University Press<br />The Global English Style Guide: Writing Clear, Translatable Documentation for a Global Market – John R. Kohl<br />A Writer’s Reference (6th Edition) – Diana Hacker<br />