Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Keep It Simple - presentation at ASTC October 2018

145 views

Published on

Various tips on how to keep your writing simple (and straightforward) for all audiences, but particularly when you are writing English content that will be translated, or consumed by non-native English speakers.
This presentation was delivered at the Australian Society for Technical Communication (ASTC) annual conference in October, 2018.

Published in: Business
  • Be the first to comment

  • Be the first to like this

Keep It Simple - presentation at ASTC October 2018

  1. 1. KISS OCTOBER 2018
  2. 2. KEEP IT SIMPLE AND STRAIGHTFORWARD
  3. 3. KEEP IT SIMPLE AND STRAIGHTFORWARD
  4. 4. KEEP IT SIMPLE
  5. 5. KIRSTY TAYLOR Twitter - @Kirstyt LinkedIn – ktaylorclpm Slides will be uploaded to SlideShare
  6. 6. WHY? • Short Attention Span (Theatre) • Our value proposition is explaining complex stuff. We are explainers. • Explaining = to make plain. • Simplicity has impact; waffle overwhelms and smothers.
  7. 7. Page 7
  8. 8. “I notice that you use plain, simple language, short words and brief sentences. That is the way to write English - it is the modern way and the best way. Stick to it; don't let fluff and flowers and verbosity creep in. When you catch an adjective, kill it. No, I don't mean utterly, but kill most of them - then the rest will be valuable. They weaken when they are close together. They give strength when they are wide apart. An adjective habit, or a wordy, diffuse, flowery habit, once fastened upon a person, is as hard to get” Mark Twain Page 8
  9. 9. “I notice that you use plain, simple language, short words and brief sentences. That is the way to write English. - it is the modern way and the best way. Stick to it; don't let fluff and flowers and verbosity creep in When you catch an adjective, kill it. No, I don't mean utterly, but kill most of them - then the rest will be valuable. They weaken when they are close together. They give strength when they are wide apart. An adjective habit, or a wordy, diffuse, flowery habit, once fastened upon a person, is as hard to get” Mark Twain Page 9
  10. 10. I notice that you use simple language, short words and brief sentences. That is the way to write English. When you catch an adjective, kill it. Kill most of them - then the rest will be valuable. They weaken when they are close together. They give strength when they are wide apart. Mark Twain (edited) Page 10
  11. 11. Page 11
  12. 12. GRAMMAR AND STYLE When considering grammar and style, follow these basic principles: Do Don’t Use active voice Use noun strings longer than two nouns Use present tense Use hidden and parenthetical plurals Use short sentences Use modal verbs Use positive constructions Overuse gerunds and present participles Include nouns determined by adjectives Use inline variables or graphics Use transitive verbs as transitive verbs Use appropriate pronoun references
  13. 13. ACTIVE VOICE AND PRESENT TENSE Use active voice for clarity and conciseness • passive voice tends to omit subjects • passive voice tends to be more lengthy Use present tense for conciseness Is passive voice the root of all evil?
  14. 14. Page 14
  15. 15. HOW DID YOU REACT? Page 15
  16. 16. POSITIVE CONSTRUCTIONS In addition to being wordy, negative constructions can cause clumsy constructions. Negative construction: Positive construction: To complete a mine haulage simulation, set up the following fundamental elements:
  17. 17. HOW WOULD YOU REPHRASE THIS TO BE POSITIVE? Page 17
  18. 18. HOW ABOUT THIS ONE? Page 18
  19. 19. COMPLETE AND CONCISE SENTENCES Keep essential words. Keep articles. Include nouns determined by adjectives. • Gross, planned, personal – what is the gender of this noun? Is it plural or singular? Avoid redundant information and expressions. • “At this point in time” could be “currently” • “ATM machine” could be “ATM”
  20. 20. KEEP ESSENTIAL WORDS Page 21
  21. 21. CAPITALISATION Use uppercase letters and lowercase letters consistently and appropriately. • Do not capitalise for emphasis. • Capitalise for UI literals, proper names, file names, and so on. Avoid capitalisation or bold to justify an acronym, for example: • Work Order (WO) – this can be Work order (WO) Entities that are special in your domain do not need to be capitalised when you are making a general reference. • To create a new work order, click New.
  22. 22. MIXING GRAMMATICAL CONSTRUCTIONS Avoid using noun forms as verbs and verb forms as nouns. Usages to avoid: hard commits • Instant message the install defaults to • Save location Keep your terminology consistent. Avoid mixing noun and verb forms in lists: • Change (infinitive) • Changing (-ing form)
  23. 23. IMPLIED NOUNS Avoid constructions with implied nouns: Activities must be configured for the following: • All working activities (for example mechanic, driver, guard, nurse) • Rostered days off (RDOs) and accrued days off (ADOs) “the following” acts as an adjective in this example, the noun is unstated. Include the noun, e.g. The following tasks, activities, items, settings.
  24. 24. HIDDEN AND PARENTHETICAL PLURALS Avoid hidden plurals • Program update -> use instead “Update of Programs” • Record deletion -> use instead “Deletion of records” • Or rephrase Avoid parenthetical plurals: • 8.Enter a Name for the created. • Start • b) adjacent to the road containing the stop sign, the at the stop sign will wait until the road is clear.
  25. 25. NOUN STRINGS Avoid heavy noun strings • They require mental energy to parse, and understand what is modifying what. Examples of long noun strings: • Loader Bucket Fill Factor fixed definitions • List Position Requirement Details • Configurator Level Sequence File Table Tag file conversion • Period Additional Quantity Currency Conversion
  26. 26. NOUN STRINGS Some ways to break up heavy noun strings: • Use hyphenation where appropriate, but don’t over-hyphenate single level bill of material single-level bill of material • Use complete sentences; include articles and prepositions
  27. 27. MODAL VERBS Modals are open to interpretation: • These fields are created in the reserving models and the user must simply identify which field should be used for each of these properties. Could be written like this, without the modal: • These fields are created in the reserving models. You can identify which field to use for each property.
  28. 28. TRANSITIVE VERBS Avoid using intrinsically transitive verbs as intransitives and vice versa: loads executes Try rewording: is loaded. runs. (Good transitive example - T An exception: • Displays – for example, a form displays, a dialog box displays.
  29. 29. GERUND AND PRESENT PARTICIPLE (PP) English forms two different grammatical categories by adding –ing to the base form of a verb: gerunds and present participles. Searching the Database - Is this an instruction or an action in progress?
  30. 30. GERUND AND PRESENT PARTICIPLE Avoid leveling headers that are only differentiated by the -ing form: Search Database » Database Searching Other languages only have one way to translate these two options: Suivi des expéditions » Suivi des expeditions Acompanhamento de Cargas -» Acompanhamento de Cargas
  31. 31. PRONOUN REFERENCES Keep one antecedent per pronoun Once the node [antecedent] is dragged onto the diagram [antecedent] its entry in the Toolbox [antecedent] is greyed out but it [pronoun] can still be renamed in the diagram window or deleted by selecting it [pronoun] and pressing the Delete key. It is not immediately clear to which antecedent “It” or “that” refers in the example above and this sentence is practically untranslatable without a clarification from the writer or a SME.
  32. 32. PRONOUN REFERENCES A pronoun should never refer to an implied idea or a title. In the example below it is not clear what the first “this” refers to nor is it clear which of the nouns “it” refers to: Quantity # This is the quantity of the scheduling data field associated with the current step. You could re-write to: The quantity of the scheduling data field that is associated with the current step.
  33. 33. ARTICLES AND PRONOUNS Avoid robotic speech; include articles and pronouns such as “the” and “that”: • When creating a manual ramp to the lowest lift, ensure (that) the Grade does not exceed reasonable values (check the grade of the segment using the tooltip after the ramp is saved). • 1.Click Enterprise Settings in the top ribbon and ensure (that) the enterprise settings are configured. • They can, for example, ensure (that) the average quality of material that reports to a stockpile during a period falls within a specific range, but this won't prevent some movements occurring above and below the limit (providing the period average is acceptable). • Empty (the) file – this one can have many interpretations – an empty file, to empty a file etc. Keep articles with their noun/noun string.
  34. 34. TERMINOLOGY When considering terminology, follow these basic principles: Do Don’t Use homographs with care Sometimes words spelled the same can have different pronunciations Overuse acronyms and abbreviations Think concept! Use jargon, puns, humor, slang and buzzwords. Avoid idioms Invent concept and words. Use maps or flags Overuse symbols
  35. 35. HOMOGRAPHS Be careful and concise with the use of homographs: • Field: a field engineer, to field a question; a data field? • Issue: Issue from inventory, an issue? • Execute : Run a program, capital punishment? • Record: To record, a record?
  36. 36. CONCEPTS Avoid using different terms to convey the same concept: • Match and reconcile • Spread, distribute and allocate • Click/push/press/hit a button Avoid using the same term to convey different concepts where possible: • Item (stock item, item of data, data in accounting?) • Order (purchase order, sales order?)
  37. 37. ACRONYMS AND ABBREVIATIONS Be careful with acronyms that may have several long forms: CMS • Customer Management System • Content Management System • Color Management System • Conversational Monitor System • ????
  38. 38. ACRONYMS AND ABBREVIATIONS Keep short forms to a minimum and to an approved list. Explain the acronym the first time it is used. Use acronyms consistently: • Unit of Measure: UoM, UOM, UM (pick one). If a word or phrase has an acronym, do not invent an abbreviation – instead of Wrk. Ord. use WO. If the software isn’t consistent, point it out! Make the developers changed the terms.
  39. 39. WILL YOUR CONTENT BE CLEAN ENOUGH? Page 40
  40. 40. SPIN THROUGH L10N Page 41
  41. 41. ACRONYMS AND ABBREVIATIONS Avoid sound based abbreviations B2B (business-to-business) • “If a supplier is established as a B2B supplier…” Never use single character acronyms • A (for ascending), D (for descending) • N
  42. 42. CULTURAL SENSITIVITY Proper Names and Marketing Concepts Political sensitivity Be mindful of how you reference other cultures:
  43. 43. INLINE VARIABLES Avoid variables/placeholders/conditional text in running text: “There's a new dive location available: The s%!” The gender and even number of the term replacing the s% will impact how “the” is translated in most other languages. Examples in Italian: • La barriera corallina (feminine) • Il cimitero delle navi (masculine) • l’abisso (masculine and contracted) As technical communicators, you can should help to improve the UI/UX text!
  44. 44. SYMBOLS Avoid using & to replace and • Most other languages do not accept & to replace and Avoid using the descriptive of a symbol without specifying the symbol: Enter the pound sign • In British English this means the currency symbol for the British pound (£) Say “Enter the number symbol (#)”
  45. 45. FLAGS AND MAPS For an international product, avoid using national flags to denote country-specific topics, translation availability, borders, culture, etc. • The Paris convention prohibits the use of national flags as trademarks (Australia has signed the treaty). • Some countries are very sensitive about how their flags are used. • A flag ≠ a language.
  46. 46. FLAGS AND MAPS Page 47
  47. 47. FLAGS AND MAPS Why do some large organisations use flags with country names? For example, apple.com • They have a fully localised website/sub-site for that country – including local taxes, local products, local imagery. • It signifies a completely localised experience, not a language. Page 48
  48. 48. ILLUSTRATIONS • Use icons sparingly and without embedded text • Use graphics sparingly and design with expansion in mind • Use screen shots sparingly and wisely • Design tables with expansion in mind • Always keep the editable source files
  49. 49. ILLUSTRATIONS Illustrations include: Graphics • Icons, images, i.e. graphics created in a graphic design tool with or without text. Screen shots • Screen shots of software UI Tables
  50. 50. ILLUSTRATIONS Things to consider when you create and include illustrations in your content: If you use a graphic, ensure that you have the editable format, i.e. the source format, available for potential translation If you include UI screen shots, ensure that you document the process and steps so that these may be easily reproduced in any translated interface.
  51. 51. ICONS Avoid culture-specific icons: • Piggy banks, engagement rings Never use icons with text Never use UI buttons with text Never use icons inline with text Recommendation: review new icons, screen designs, etc, for global considerations. ISO/IEC 11581 is a standard for global icons.
  52. 52. EXAMPLES OF ICONS NOT SUITED FOR A GLOBAL AUDIENCE
  53. 53. ICONS INLINE IN TEXT Word order and placement will vary by language. Inline graphics mean more work for every language you translate into. If icons have to be used for illustration, place at the end of the sentence, or use a popup on hover or similar. Avoid using colour coding for emphasis* View Tasks * Yes, I have done that in this presentation …
  54. 54. SCREEN SHOTS • Limit screen shots • Avoid call-outs with text • Script the screen capture steps • Include instruction if auto scripting is not an option • Link screens to content where possible/practical (instead of embedding non-editable graphics) • Think about data before capturing (will the same data be available/usable in a translated environment?) • Think about language/culture-specific data entry (date/currency) • If you need to explain a screen, use numbered callouts and associate the explanation with the number as text in a table.
  55. 55. TABLES Avoid cluttered tables in English: Consider vertical table structures: Consider separating into several tables Organisationsei nheit (US- Dollar) Lan des wäh rung Fremd währu ng Währu ngsco de Wechs elkurs Kosten in Landes währun g Einhei ten Kosten in Fremdw ährung Rechnun g in Landesw ährung Für Rechnung 501 USD Euro E 5.68 50.00 10 284.00 575.00 3266.00 Organisationseinheit (US-Dollar) 501 Landeswährung USD Fremdwährung Euro Währungscode E Wechselkurs 5.68 Kosten in Landeswährung 50.00 Einheiten 10 Kosten in Fremdwährung 284.00 Rechnung in Landeswährung 575.00 Für Rechnung 3266.00
  56. 56. ILLUSTRATIONS WITH TEXT • Design for expansion! • Avoid graphic layers and grouping • Do not use hard returns to go to the next line in text boxes: • Do not split sentences into separate text boxes • Limit fonts to standard fonts
  57. 57. EXAMPLES OF TEXT EXPANSIONS Consider text expansion Consider larger fonts – Asian languages English term Translation Languag e Edit Bearbeiten German Sort Ascending Lajittele nousevassa järjestyksessä In aufsteigender Folge sortieren Finnish German Task Documentation Cross Reference Aufgabendokumentationsqu erverweise German Cancel Abbrechen German
  58. 58. TEXT EXPANSION – RULE OF THUMB Number of characters in the source language (including spaces) Additional space required for translation into average target language Up to 10 100% to 200% 11 to 20 80% to 100% 21 to 30 60% to 80% 31 to 50 40% to 60% 51 to 70 31% to 40% Over 70 30% The shorter the word – the more space needed!
  59. 59. In an advertisement by a Hong Kong dentist… Teeth extracted by the latest Methodists. HALL OF SHAME
  60. 60. REFERENCES Plain English Campaign http://www.plainenglish.co.uk/free-guides.html Paris Convention http://www.wipo.int/treaties/en/ip/paris/index.html ISO/IEC 11581 - standards for global icons Write Tight(er) presentations – Marcia Riefer Johnston http://writing.rocks/write-tighter-presentation/ How Writing Works – Roslyn Petelin Write101x – edX - https://www.mooc-list.com/course/english-grammar-and-style-edx
  61. 61. TWEEPS @SinAndSyntax – Constance Hale @GrammarGirl – Mignon Fogarty @MarciaRJohnston – Marcia Riefer Johnston @Acrolinx – Acrolinx corporation Page 63

×