LavaCon2018: Workshop day

I’m in New Orleans and it’s Sunday, which means it’s workshop day at the LavaCon conference! I attended Melinda Belcher’s Preparing Technical Content for Translation half-day workshop. There were about 15 people in the workshop and several were from other countries, so there were lots of perspectives and good information sharing. Some people were in the early stages of translation projects, others were well into it, and yet others were just trying to get information to tailor their documentation so that it was ready for translation sometime in the future.

Here are my notes from Melinda’s session.

Her focus was on optimising content for translation in terms of:

• Clarity
• Structure
• Format
• Localisation strategy.

Much of what she had to say was very similar to the principles of the plain language movement.

Clarity

• Keep sentences brief
• Use as few words as possible
• Short words are better than long words
• Use plain English to make your point
• Use a single term to identify a single concept
• Write so your audience can understand you
• Test your word choice and sentence design

Structure

• Avoid unnecessary complexity
• Lighten the cognitive load through strategic delivery of information
• Use Standard English word order whenever possible
• Use the active voice rather than the passive
• Use relative pronouns like ‘that’ and ‘which’
• Avoid phrasal verbs (containing a verb form with one or more articles)
• Avoid long noun strings

Format

• Make sure it fits (e.g. German takes much more space than the English equivalent)
• Be clear with international dates and measurements etc.
• Allow extra space for translated words
• Allow extra time for formatting text in languages that read from right to left
• Make readers aware of other [language] versions

Localisation strategy

• Avoid humour
• Strengthen your organisation’s capacity for translation oversight (not just words – cultural nuances, context, fonts, non-Romanised languages, compound words, dialects, other influences)
• Establish and implement written guidelines for translation methods and for assessing the qualifications of a translator/agency
• Consider a transcreation process (not necessarily good for long text, but may work well for marketing material [e.g. taglines, slogans, apps])
• Other approaches to translation: single one-way translation; multiple one-way translation; reverse translation (i.e. translation back into English)

Early on in the session, she made a comment about text embedded in images – get the words out of the images and put them into callouts, captions etc.

She also mentioned these tools:

• Hemingway app (http://www.hemingwayapp.com/)
• Rewordify – tests word understandability (https://rewordify.com/)
• Schematron – open source tool for checking language (https://en.wikipedia.org/wiki/Schematron)

Gobbledygook, jargon, and plain language

Based on a writing tip I wrote recently for my work colleagues. The industry is oil and gas. And yes, I know that ‘bottom line’ qualifies for Buzzword Bingo ;-)

***************

Bottom line:

• Use plain language where possible so the reader doesn’t have to try to figure out what you mean.
• Consider how you would explain the concept to your parents, children, grandparents, those who don’t work in the industry etc. – and then use that language in your writing. Plain, simple, and easily understood.
• Every time someone has to stop and think while reading your document, the organisation incurs a cost – time, lost productivity, rework etc.
• Every misinterpretation could put a life at risk.

Let’s look at some examples from some documents I’ve reviewed:

Phrase as written by the author	My comments
‘Each sub-phase will be reviewed and assured prior to proceeding to the next sub-phase.’	What does ‘assured’ mean in this context? None of the dictionary meanings fit how it’s used in this sentence. Does it mean ‘confirmed’, ‘approved’ or something similar? If so, use one of those words so that the reader isn’t confused. (By the way, the Macquarie Dictionary definitions for ‘assured’ are: 1. [adj] made sure; sure; certain. 2. [adj] bold; confident. 3. [noun] boldly presumptuous. None of these really fits the sentence, though I suspect a variation of the first definition is the closest.)
‘could leverage synergies with’	This one would qualify as a BINGO! in Buzzword Bingo (see links below). Consider using plainer language, e.g. ‘take advantage of’, ‘cooperate with’, ‘combine with’, ‘joint opportunity’ etc.
‘to enable performance characterisation of the…’	More business jargon and another candidate for Buzzword Bingo. What does ‘performance characterisation’ mean? How would you explain this to your parents, for example?
‘does not contain a sufficiently large portion’	While the individual words are in plain language, ‘sufficiently’ and ‘large’ are relative terms. What does ‘sufficiently large’ mean in this context? Larger than what? How ‘sufficient’ does it have to be to be ‘sufficiently large’? Either be specific about the size of the portion (using a value and unit of measure) or reword.

For each example listed above, I had to stop and think, try to figure out (guess!) what the author meant, consult the dictionary, or do all these actions. Each hesitation was a distraction that took my focus away from my objective of reading and understanding the content. Each time I searched the dictionary or thesaurus and tried out alternative words in my head, my focus was off the document and onto something else. Instead of reading a paragraph and knowing straight away what it meant, I was distracted – and sometimes confused. Thus the time I took to read and understand the sentence, paragraph, entire document was compromised. And that’s just me. Multiply that lost time by the number of readers of your documents who don’t understand what you mean and thus have to try to figure it out and now there’s a much bigger issue than just a silly word or two.

Let’s say your document is read by 30 people, and each person ‘loses’ just 10 minutes on that one document trying to understand what you’re saying. That’s a business cost of 300 minutes (5 hours) to the organisation for ONE document—a cost that could have been prevented if you’d spent just an extra minute or two converting gobbledygook and business jargon into plainer language. Multiply that over the thousands of documents produced and read by thousands of employees and contractors per year and now you’re looking at a substantial cost to the organisation.

But potentially there’s an even bigger business cost than lost time, and that’s the cost of misinterpretation. Sure, for many documents misinterpretation of a single word or phrase doesn’t matter too much. But ours is an industry [oil and gas] where lives may be at risk if an instruction is misinterpreted, or if a specification uses an incorrect unit of measure (e.g. inches instead of centimetres, grams instead of milligrams) or doesn’t specify a measure (‘sufficiently large’), or if a comma is in the wrong place thus making a sentence ambiguous and open to misinterpretation.

Loss of life, law suits, government inquiries etc. are all potential costs of misinterpretation.

So, after you write a sentence/paragraph/section/document, read it through before finalising it to make sure that all the words/phrases you use will be understood by your target audience. If in doubt, think about how you’d explain it to someone outside the industry and use those words instead. Or get someone else to read it and alert you to anything they can’t understand or that they hesitate over.

See also:

• Varanus Island Incident Investigation: http://www.parliament.wa.gov.au/WebCMS/WebCMS.nsf/resources/file-varanus-report/$file/varanusinquiry2.pdf (specifically, Chapter 1 which details the documentation – and lack of it – regarding the pipeline, operations, inspections, specifications etc.)
• The comma that cost a million dollars: http://www.nytimes.com/2006/10/25/business/worldbusiness/25comma.html?_r=1
• Legal implications of incorrect wording on a document: http://www.ehow.com/about_6494887_legal-implications-incorrect-wording-document.html
• The costs of poor communication: http://www.solari.net/toward-humanity/2009/10/18/the-costs-of-poor-communication/
• Simple word and phrase alternatives: http://www.plainlanguage.gov/howto/wordsuggestions/simplewords.cfm
• A-Z of alternative words: http://www.plainenglish.co.uk/files/alternative.pdf
• Clear or plain language: http://taitcc.com/blog/?p=134

And for fun:

• http://www.plainenglish.co.uk/examples/gobbledygook-generator.html
• http://www.businessbuzzwordbingo.com/

[Links last checked October 2012]

The power of plain English

I was unable to go to the ASTC (NSW) Conference this year, which was held in Sydney in conjunction with the Plain English Foundation’s international conference. However, I’ve been reading some glowing reports from various attendees.

One mentioned Angela Colter’s presentation on the assessment of credit card disclosure documents that she did for the US Government Accountability Office (GAO). The slides are interesting, but for me, there were two that REALLY stood out.

The first shows the median reading level of US adults (Grade 8), against the reading grade level of card member agreements (Grade 12) and annual percentage rate information (Grade 17). Scary stuff:

The second illustrated the power of plain English by comparing text on one of those credit card agreements before and after plain language principles were applied:

Some of the presentations from this conference are available here: http://www.plainenglishfoundation.com/Paperspresentations/Workshoppapers/tabid/3292/Default.aspx

See also:

• [Plain] Language Resources: https://cybertext.wordpress.com/2008/06/30/language-resources/

[Links last checked November 2009]

Book review: The Global English Style Guide

The subtitle of John R. Kohl’s The Global English Style Guide is Writing Clear, Translatable Documentation for a Global Market — and that says it all, really.

This book is a fabulous resource for any technical writer, whether your writing is likely to be translated into another language or not. There are plenty of readers of our documentation whose first language is not English, and others who have difficulties with the nuances of the English language. Just like good design for accessibility is good design for all, technical communicators who follow the writing recommendations in this book should end up with technical documentation that’s clearer for everyone.

In addition, clear writing should save money in translation costs by reducing the ‘to-ing and fro-ing’ of the “What do you mean here?” questions by the translation agency.

Kohl provides hundreds of practical examples in his 300 page book. These examples are aimed directly at technical writers — particularly those who write software documentation.

Everything is set out clearly, with a comprehensive table of contents, a glossary, a bibliography of further resources, and an index. And it’s peppered with notes and hints and tips.

I read this book over a few nights (yes, that’s sad — reading a style guide for pleasure!), and highly recommend it for any technical writer’s arsenal of style guides.

You can purchase this book via the CyberText bookstore (affiliated with Amazon.com): http://astore.amazon.com/cybertconsul-20/detail/1599946572

List of plain language alternatives

Having edited hundreds of scientific reports in the past few months, I have seen some pretty ordinary writing — unclear, passive voice, third person, future tense, assigning actions to inanimate objects, disagreements between subjects and verbs, etc.

But the worst offenders are the words the authors continue to utilize use, perhaps in the hope that their reports may sound more learned. Wrong! It just makes them harder to read and understand.

There’s a lot to be said for clear writing, and finally governments around the world are doing something about it. The US Federal Government, for example, has this:

On June 1, 1998, President Clinton issued an executive memo requiring agencies to write in plain language. Several statutes have also admonished agencies to write certain types of documents in plain language. In 2004, an interagency task force working on behalf of the Office of Management and Budget called for federal websites to be written in plain language. (from: http://www.plainlanguage.gov/whatisPL/index.cfm)

And on the US Federal Government’s Plain Language website, they have a list of recommended simple words and phrases: http://www.plainlanguage.gov/howto/wordsuggestions/simplewords.cfm

Note: The Plain English Foundation and the ASTC (NSW) are joining forces to host the Plain Language Association InterNational (PLAIN) annual conference in Sydney in October 2009. Conference details…

[Links last checked November 2011]

Work for hire contract in plain English

Andy Clarke has shared his terrific plain English ‘killer’ contract with the world. It’s an ideal starting point for independent contractors such as writers, graphic designers, web developers, etc. for dealing with their clients’ projects.

You can see the essentials of his contract here: http://24ways.org/2008/contract-killer (don’t forget to look at the Comments too).

Text version.

(Thanks to Art C on the STC Contractors and Independent Consultants SIG discussion list for alerting me to this site)

[Links last checked March 2009]

Avoid culturally specific references

One of the tenets of good technical communication is to avoid culturally specific references, especially if your material is to be translated into other languages. But what’s a culturally specific reference? In simple terms, it’s a word or phrase that has meaning for members of a cultural group, but has limited meaning, no meaning, or some other meaning for people outside that group.

Culturally specific terms are typically those commonly known within one country but not another. Within a country, it can refer to terms known to one region but not another, or words spoken by different ‘tribes’ (e.g. differences in terms used in generational groups, industry groups, ethnic groups, etc.).

Some culturally specific terms are easy to identify — names of foods and beverages, for example (pop, soda, coke, soft drink…). But other times they’re not so easy, especially if you don’t even realize that the term or phrase might not be known by others. Time spent visiting and living in various parts of the world helps in understanding such differences, but is only a start. The best way to identify culturally specific terms is to get someone from outside the expected audience demographic to read your material — look for people from different age groups (if generational language may be important); from different regions, states, countries; from different educational levels; from different ‘tribes’.

Sometimes what appears to be a common term to you, is not so common to others or in other contexts.

An example of a culturally specific term that I encountered in someone’s email to a global audience was ‘water cooler’. The context was using it in a mission statement — “To provide a virtual water cooler for an international community of [occupation] …, where they can share ideas, solutions, technology, professional support, and encouragement.”

My response to that suggestion was:

I believe that ‘water cooler’ is fairly US-centric as a term. It’s not commonly used in Australia, for example (I can’t speak for the rest of the world, obviously), though it’s gaining currency as we take to bottled and filtered water more and more — and as Dilbert and friends reach a wider audience. While many offices and homes now use such things, most would still use tap water.

I can recall visiting the US for the first time in 1985 and being amazed (and quite horrified) that friends had these large water bottles and coolers in their own homes. For me, drinking water had always come out of a tap and I couldn’t understand why you would get your drinking water any other way. For much of the developed world, that’s how it still comes — and for other parts of the world, it might be the village pump (which I guess is a very early version of a ‘water cooler’ community).

So, much as I personally like — and relate to — the term, I’d be interested to hear how others respond to a term that may be specific to either a geographic region or to a particular socioeconomic class.

One technique I use to check terms I’m not sure that a US audience would be familiar with is to have a ‘buddy’ in the US — a friend I can email or ping (‘send an instant message’) with really quick questions about language I *think* may be culturally specific (hi Char!).

Find yourself a buddy — they’re an invaluable resource!

Plain English, please

David Pogue, the technology writer and blogger for The New York Times, has taken other technology writers to task over their use of jargon.

While I agree with his points and examples in principle, he seems to forget one thing—’know your audience’. If you’re writing about technology to a general ‘Mom and Pop’ readership, then yes, avoid the jargon where possible. But if you’re writing about technology to a geeky audience, then you have to use terms familiar to that audience, or terms that clearly mean what you want to say. In particular, David Pogue talks about avoiding terms like ‘web content’ and ‘RAM’, but for certain audiences it is necessary to be this specific as these terms have quite distinct meanings from the generic ‘web page’ and ‘memory’ that he offers as preferable terms.

You can see his article and the many comments and other suggestions he’s received about it here:
http://pogue.blogs.nytimes.com/2008/10/16/tech-terms-to-avoid/

[Link last checked 20 October 2008]