Download to read offline
![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.](https://image.slidesharecdn.com/kissastcoct2018-181014225914/85/Keep-It-Simple-presentation-at-ASTC-October-2018-32-320.jpg)
Uploaded byKirsty Taylor, CLPM
Keep It Simple - presentation at ASTC October 2018
The document emphasizes the importance of simplicity in communication, advocating for plain language, short sentences, and the active voice to improve clarity and impact. It highlights various principles of grammar and style while providing guidance on avoiding verbosity, mixed constructions, and redundant terminology. The overall goal is to enhance understanding and efficiency in technical communication by fostering concise and precise writing habits.
More Related Content
![Bus com05[1] 1](https://cdn.slidesharecdn.com/ss_thumbnails/buscom0511-110309033512-phpapp01-thumbnail.jpg?width=640&height=640&fit=bounds)
Similar to Keep It Simple - presentation at ASTC October 2018
Keep It Simple - presentation at ASTC October 2018
- 1.
- 2. KEEP IT SIMPLEAND STRAIGHTFORWARD
- 3. KEEP IT SIMPLEAND STRAIGHTFORWARD
- 4.
- 5. KIRSTY TAYLOR Twitter -@Kirstyt LinkedIn – ktaylorclpm Slides will be uploaded to SlideShare
- 6. WHY? • Short AttentionSpan (Theatre) • Our value proposition is explaining complex stuff. We are explainers. • Explaining = to make plain. • Simplicity has impact; waffle overwhelms and smothers.
- 7.
- 8. “I notice thatyou 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. “I notice thatyou 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. I notice thatyou 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.
- 12. GRAMMAR AND STYLE Whenconsidering 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. ACTIVE VOICE ANDPRESENT 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.
- 15. HOW DID YOUREACT? Page 15
- 16. POSITIVE CONSTRUCTIONS In additionto 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. HOW WOULD YOUREPHRASE THIS TO BE POSITIVE? Page 17
- 18. HOW ABOUT THISONE? Page 18
- 20. COMPLETE AND CONCISESENTENCES 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”
- 21.
- 22. CAPITALISATION Use uppercase lettersand 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.
- 23. MIXING GRAMMATICAL CONSTRUCTIONS Avoidusing 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)
- 24. IMPLIED NOUNS Avoid constructionswith 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.
- 25. HIDDEN AND PARENTHETICALPLURALS 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.
- 26. NOUN STRINGS Avoid heavynoun 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
- 27. NOUN STRINGS Some waysto 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
- 28. MODAL VERBS Modals areopen 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.
- 29. TRANSITIVE VERBS Avoid usingintrinsically 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.
- 30. GERUND AND PRESENTPARTICIPLE (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?
- 31. GERUND AND PRESENTPARTICIPLE 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
- 32. PRONOUN REFERENCES Keep oneantecedent 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.
- 33. PRONOUN REFERENCES A pronounshould 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.
- 34. ARTICLES AND PRONOUNS Avoidrobotic 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.
- 35. 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
- 36. HOMOGRAPHS Be careful andconcise 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?
- 37. CONCEPTS Avoid using differentterms 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?)
- 38. ACRONYMS AND ABBREVIATIONS Becareful with acronyms that may have several long forms: CMS • Customer Management System • Content Management System • Color Management System • Conversational Monitor System • ????
- 39. ACRONYMS AND ABBREVIATIONS Keepshort 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.
- 40. WILL YOUR CONTENTBE CLEAN ENOUGH? Page 40
- 41.
- 42. ACRONYMS AND ABBREVIATIONS Avoidsound 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
- 43. CULTURAL SENSITIVITY Proper Namesand Marketing Concepts Political sensitivity Be mindful of how you reference other cultures:
- 44. INLINE VARIABLES Avoid variables/placeholders/conditionaltext 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!
- 45. 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 (#)”
- 46. FLAGS AND MAPS Foran 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.
- 47.
- 48. FLAGS AND MAPS Whydo 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
- 49. ILLUSTRATIONS • Use iconssparingly 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
- 50. 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
- 51. ILLUSTRATIONS Things to considerwhen 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.
- 52. 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.
- 53. EXAMPLES OF ICONSNOT SUITED FOR A GLOBAL AUDIENCE
- 54. ICONS INLINE INTEXT 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 …
- 55. SCREEN SHOTS • Limitscreen 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.
- 56. TABLES Avoid cluttered tablesin 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
- 57. 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
- 58. EXAMPLES OF TEXTEXPANSIONS 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
- 59. 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!
- 60. In an advertisementby a Hong Kong dentist… Teeth extracted by the latest Methodists. HALL OF SHAME
- 62. REFERENCES Plain English Campaign http://www.plainenglish.co.uk/free-guides.html ParisConvention 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
- 63. TWEEPS @SinAndSyntax – ConstanceHale @GrammarGirl – Mignon Fogarty @MarciaRJohnston – Marcia Riefer Johnston @Acrolinx – Acrolinx corporation Page 63
Editor's Notes
- #7 Hat tip to Bonni Graham for the phrase “Short Attention Span Theater” Complex ideas – or procedures, or products, or physical structures, Matt Furse, a Digital Transformation Specialist at Microsoft AU described the jobs for a new era in 2017 as these three – Trainers, Explainers, and Sustainers.
- #11 That was a quick edit, through the most egregious elements of the text. This text could be edited more precisely! What would you do?
- #14 13
- #16 How does a negative construction make you react vs a positive one?
- #17 16
- #19 Nothing is better than chocolate! Could have emphasised that this superfood is free from all of these so-called nasties, rather than emphasising No. But which has the larger impact for this message?
- #20 Time to drink from the fire hose
- #21 20
- #23 22
- #24 23
- #25 24
- #26 25
- #27 26
- #28 27
- #29 28
- #30 29
- #31 30
- #32 31
- #33 32
- #34 33
- #35 34
- #36 Some of these rules may vary if you have a strictly homogenous audience – no variation in ethnic background, languages spoken, living locale.
- #37 36
- #38 37
- #39 38
- #40 39
- #43 42
- #44 43
- #45 44
- #46 45
- #47 46
- #48 English – which flags do you include? Which don’t you include? Who do you annoy with your choice? Is that choice deliberate or accidental?
- #50 49
- #51 50
- #52 51
- #53 52
- #54 53
- #55 54
- #56 55
- #57 56
- #58 57
- #59 58
- #60 59
- #61 60
- #63 62