Webinar presented to NZ Tech Comm in July 2019. Tips on how to improve the quality of your technical writing.

1. KISS
July 2019

2. KEEP IT SIMPLE AND
STRAIGHTFORWARD

3. KEEP IT SIMPLE AND
STRAIGHTFORWARD

4. KEEP IT SIMPLE

5. • Twitter - @Kirstyt
• LinkedIn – ktaylorclpm
• Slides will be uploaded to SlideShare
KIRSTY TAYLOR

6. • 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.
WHY?

7. Page 7

8. Page 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

9. Page 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

10. Page 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)

11. Page 11

12. WHEN CONSIDERING GRAMMAR AND STYLE, FOLLOW THESE BASIC PRINCIPLES:
GRAMMAR AND STYLE
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. 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?
ACTIVE VOICE AND PRESENT TENSE

14. Page 14

15. Page 15
HOW DID YOU REACT?

16. • In addition to being wordy, negative constructions can cause clumsy constructions.
Negative construction:
A mine haulage simulation cannot be completed without the following fundamental elements:
Versus
Positive construction:
To complete a mine haulage simulation, set up the following fundamental elements:
POSITIVE CONSTRUCTIONS

17. Page 17
HOW WOULD YOU REPHRASE THIS TO BE POSITIVE?

18. Page 18
HOW ABOUT THIS ONE?

20. 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”
COMPLETE AND CONCISE SENTENCES

21. Page 21
KEEP ESSENTIAL WORDS

22. 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.
CAPITALISATION

23. • Avoid using noun forms as verbs and verb forms as nouns. Usages to avoid:
• The system hard commits the quantity
• Instant message me.
• Complete the install
• This check box defaults to de-selected.
• Save location
Keep your terminology consistent.
• Avoid mixing noun and verb forms in lists:
• Change Mining Direction (infinitive)
• Changing an Activity Area Mining Level (-ing form)
MIXING GRAMMATICAL CONSTRUCTIONS

24. 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.
IMPLIED NOUNS

25. 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.
HIDDEN AND PARENTHETICAL PLURALS

26. 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
NOUN STRINGS

27. Some ways to break up heavy noun strings:
• Use hyphenation where appropriate, but don’t over-hyphenate
• “single level bill of material” could be “single-level bill of material” (but not single-level bill-of-material)
• Use complete sentences; include articles and prepositions
NOUN STRINGS

28. 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.
MODAL VERBS

29. Avoid using intrinsically transitive verbs as intransitives and vice versa:
If…, the model loads. (loads what?)
The program executes. (executes what?)
Try rewording:
If…, the model is loaded.
The program runs.
(Good transitive example - The Run function executes all incomplete steps in the process, up to an including the
current step)
An exception:
• Displays – for example, a form displays, a dialog box displays.
TRANSITIVE VERBS

30. 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?
GERUND AND PRESENT PARTICIPLE (PP)

31. 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
GERUND AND PRESENT PARTICIPLE

32. 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.
PRONOUN REFERENCES

33. 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.
PRONOUN REFERENCES

34. 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.
ARTICLES AND PRONOUNS

35. WHEN CONSIDERING TERMINOLOGY, FOLLOW THESE BASIC PRINCIPLES:
TERMINOLOGY
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. 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?
HOMOGRAPHS

37. 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?)
CONCEPTS

38. Be careful with acronyms that may have several long forms:
CMS
• Customer Management System
• Content Management System
• Color Management System
• Conversational Monitor System
• ????
ACRONYMS AND ABBREVIATIONS

39. 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.
ACRONYMS AND ABBREVIATIONS

40. Page 40
WILL YOUR CONTENT BE CLEAN ENOUGH?

41. Page 41
SPIN THROUGH L10N

42. 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)
• In German both meanings start with A
• N
• What is the context for the audience to understand what this means?
• No
• This could be Non or Nº (Numero) in French.
ACRONYMS AND ABBREVIATIONS

43. Proper Names and Marketing Concepts
Version 4 -> 4 = death in some Asian languages
Political sensitivity
Be mindful of how you reference other cultures:
• Products used in the Chinese market must not refer (directly or implicitly) to Taiwan, Hong Kong or Macao as countries.
CULTURAL SENSITIVITY

44. 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!
INLINE VARIABLES

45. 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 (#)”
SYMBOLS

46. 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.
FLAGS AND MAPS

47. Page 47
FLAGS AND MAPS

48. Page 48
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.
FLAGS AND MAPS

49. • 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
ILLUSTRATIONS

50. 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
ILLUSTRATIONS

51. 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
.docx, .vsdx, .ai, .psd are editable formats
.pdf, .gif, .jpg are not editable formats
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.
ILLUSTRATIONS

52. 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.
ICONS

53. EXAMPLES OF ICONS NOT SUITED FOR A GLOBAL AUDIENCE

54. 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.
3. Click View Tasks
Avoid using colour coding for emphasis*
3. Click View Tasks
* Yes, I have done that in this presentation …
ICONS INLINE IN TEXT

55. • 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.
SCREEN SHOTS

56. Avoid cluttered tables in English:
Consider vertical table structures:
Consider separating into several tables
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. • Design for expansion!
• The shorter the text string the greater the space needed for
translation.
• Avoid graphic layers and grouping
• Do not use hard returns to go to the next line in text boxes:
• Set text boxes to resize and wrap text instead of using hard
returns
• Do not split sentences into separate text boxes
• Limit fonts to standard fonts
ILLUSTRATIONS WITH TEXT

58. • Consider text expansion
• Consider larger fonts – Asian languages
EXAMPLES OF TEXT EXPANSIONS
English term Translation Language
Edit Bearbeiten German
Sort Ascending Lajittele nousevassa
järjestyksessä
In aufsteigender Folge
sortieren
Finnish
German
Task
Documentation
Cross Reference
Aufgabendokumentationsquer
verweise
German
Cancel Abbrechen German

59. 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%
TEXT EXPANSION – RULE OF THUMB
The shorter the word – the more space needed!

60. In an advertisement by a Hong Kong dentist…
Teeth extracted by the latest
Methodists.
HALL OF SHAME

62. 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
REFERENCES

63. Page 63
• @SinAndSyntax – Constance Hale
• @GrammarGirl – Mignon Fogarty
• @MarciaRJohnston – Marcia Riefer Johnston
• @Acrolinx – Acrolinx corporation
TWEEPS