We discuss 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.
Kirsty Taylor is Manager, Product Internationalisation at RPM Global.
Kirsty’s presentation was delivered at the Australian Society for Technical Communication (ASTC) annual conference in October, 2018.
You can see the slides at https://www.slideshare.net/kirstymtaylor/keep-it-simple-presentation-at-astc-october-2018
Normally, the way I start this is asking people to introduce themselves what they do and I suppose it’s relevant to you where they are.
Sure I’m Kirsty Taylor I’m a manager of product internationalization for a company called RPM Global
We produce mining software so all kinds of mining there’s quite a variety in the world of mining from open cut and underground and all different commodities mined
And I just joined RPM in August of this year, so been there just over two months, and I’m coming to grips with what we do and learning a lot in that space
Do you have a team of people that report to you or you work with?
I’m part of the research and development or technology business unit
We’re not we’ve got a fairly flat hierarchy so I don’t have a team reporting to me I’m working across all of the different development teams we’ve got I think about five or six different product domains so I’m working with each of those product domains we’ve got one new UX person
I’ve been working with him and a couple of technical writers they I see quite close to them and I’m starting to work with them on their content as well
So that’s how we kind of structured at the moment
Then we have other divisions that I’m interacting with
I’m working with the marketing team
I’ve started talking to some of our consulting team we do two different kinds of consulting which is a bit new to me we do consulting on our software products but we also do what we call advisory consulting which is actually more general business consulting in the mining industry and it’s completely separate to our software sales
And you’re based in or near Brisbane?
I’m based in Brisbane Australia so right in the centre of the city
I’ve lived in Brisbane for almost my whole life apart from a few years when I was running around in the outback as a small child and yeah based riding in part of Brisbane now and I’ve been working in Brisbane in technical communication and internationalization for almost 20 years now
And you’re fluent in German and English?
Yes, I’d say fairly fluent in German and English
I don’t get to use my German as much as I’d like, unfortunately
And then I I studied little bits of Italian and Japanese at primary school in high school and I’ve throughout my career in the internationalization I’ve learned all kinds of handy words such as tab and work order and click in Russian and Spanish and a few other languages that well
I’m not sure if I can pronounce some of them properly but I can recognize them when they’re written
You were saying when you presented at the ASTC conference and the Gold Coast your topic was “keep it simple”. How long was your presentation? What was the talk about?
It was a 45-minute presentation
If you have looked at the slides on SlideShare or something that is actually probably the full slides for an hour to an hour and a half presentation.
So I didn’t go through all of the slides in that presentation there was there was too much content for it, but I wanted to put some of the extra content in there for attendees to have access to afterwards
I guess I found over the last 10 plus years that the areas I work in in the areas that I can talk about it at conferences include management of technical running teams management of global technical writing teams internationalization, both software internationalization and writing for a global audience so that you’ve got good English content that can be more easily translated than if it were lower quality content and then be translated successfully into other languages
A lot of people don’t realize they expect translators who have never seen your software maybe they do know about mining being our business domain, but they may not have used software like ours.
They may know it from university studies more than working in a mine being presented with XML extracts out of a documentation authoring tool that is maybe single sourced and compiled into a huge number of topics.
People who are working on that content in those products all the time don’t realize this is probably analogous to a technical communicator being asked to document a software system based purely on specifications or user stories or design documents and never getting to see this software and run it and understand the business processes behind it
So often when you translate you can get a drop in quality just by the nature of the process that can occur depending on how involved your translators are and what your process is so if you if your quality your content is not of the best possible quality you can produce, you’re doing a disservice to your future translations and translators can’t just make up for that quality gap
So your presentation was on tips for keeping your writing style simple and straightforward for it to be translated
That’s probably when the crux of this expertise has come from, but I believe these sorts of tips can stand just as well if you’re not translating or if you don’t know you’ll be translating
And then down the track three or four years you do end up translating
There were some other presentations from technical communicators and managers from Boeing Defense. Boing is quite one of the larger employers of technical communicators here in Brisbane and they’re producing various forms of aircraft, though they had a special word was it air vehicles or if there was something like that that they used helicopters and the like that they’re producing for the Australian Defence Force and that their content is never going to be translated, but they were talking through using Simplified Technical English and a lot of that the tips from my presentation cross over to Simplified Technical English where you know don’t omit articles from your content, turn it into that robotic speech.
Yes it cuts down on words and you pay by the words for translation, but you’re actually doing a disservice by trying to cut down the words in that way.
So whilst it was for translation, it’s still I think some very good basics, for some good simple writing in terms of advice for people to write simply
And the main items of advice that you pass on, a lot of it, and I went through some of these slides with the technical writers at work last week, and as we’re going through some of them, one of them pointed out ,oh you know this is really basic technical communication information.
And it is but sometimes we need to be reminded of those basics when the subject matter, particularly the both academic style subject matter experts bog us down with the original content that we might have to rewrite or are using as source material and to use that for our content.
So it is it’s all basic stuff you know using active voice.
If you do use passive voice, make sure it’s deliberate you know there are times where passive voice is okay it’s not the root of all evil
If you really want to take the actor out of the particular sentence or the idea then passive voice is okay
Using present tense, watching out for your modal verbs – they can be really problematic: will, should, may, etc we should be should be her speaker.
And then as I found during the presentation, what if what you speak sometimes might be different and a bit more verbose than how you might write
So in if something should be done you know is that must or you know is there some kind of yes/no
You don’t have to or you do have to make sure that’s really clear with your writing
Having short sentences
Trying to use positive constructions
And there’s certainly that trend in UX writing as well with error messages and messages to users in your user interface to not focus on, all bad user, you made an error, warning warning Will Robinson,
But we may head into you know, I’ll make sure you put the right format for your postcode or whatever
Here we we’re looking for a hyphen or something make sure you don’t have adjectives sitting there without nouns, adjectives modifying the nouns.
That is that they can be a tendency in English
We can accept kind of these unstated nouns, but other languages you can’t
Transitive verbs – make sure they’re transitive. Keep your language consistent
Have simple sentences
Watch out for your parenthetical plurals
They’re really problematic in other languages
So other languages can’t just add an S or an es onto the end of a word, or the equivalent of that to form a plural, so maybe just write everything in plural form or try to rewrite to avoid the singular or plural optionally
Maybe it isn’t the most critical thing that that sentences number agreement has to agree with the number of records the software’s returning in that function, or something
I think you mentioned words and phrases to avoid
Yes exactly and you know all these words that we don’t realize when we’re speaking that can be problematic as well
When it’s written down and we’re taking the word just as a standalone word is record
Is it record or record, so is it a noun or a verb?
Is there enough information there for a translator or someone who has English as a second language or as a foreign language to understand what that is, without them having to spend much longer parsing and trying to understand the meaning of what you’re trying to convey
So it’s those were some of the the big tips on grammar and style yeah, and I thought listen to good advice on the slide that
I saw a lot of it overlaps with some of the basic grammar and writing principles that we cover in technical writing foundation course. It was good to see.
I did notice something in your presentation we just get to the right intersection it was about gerunds and the present participle, and how you write headings
So there’s a trend with companies, particularly with developer documentation, where in the past we might have written “searching the database: and now companies are using “search the database” or “search database”. and you talked about some of the implications or pros and cons of using those, and how that impacts on translation.
When it gets translated into other languages like French and Spanish
So can you tell me a bit more about the problems with that and ways around it?
There’s a couple of problems just distinguishing between the gerund and the present participle you know across languages and making sure that distinction is clear
There can be you know certain of these grammatical terms that we aren’t aware of those distinctions potentially as native speakers, unless you have undertaken some linguistic studies or studied other languages and realized how that maps back to English.
Because I know I certainly never talked about present participles ever at school, until I hit university doing a linguistics degree and doing my business German degree.
That was when I really got into these sorts of nitty-gritty grammatical terms, but the real problem is where other languages, and with the examples I gave with French and Spanish particularly, they can’t distinguish between search database, and database searching, or searching the database.
They would be translated exactly the same
So what we may perceive as a nice distinction between the gerund, the ing-form, and then now we get down to what a nice imperative mood, search the database, potential heading, that distinction just may not transfer across
So what I ultimately wanted people to take away from that is, maybe not to worry so much about the gerund and present participle, but to make sure when you’ve got a heading structure that there’s really meaningful differences with your headings rather than OK, well my heading one or my heading two or whatever you know, that’s database searching and now I’m going to go down to the next level and now I’ve got actually the step by step going on.
I’m going to say search the database if you’re going to be really just moving your words around slightly, having a different verb form, moving the words around in your phrase.
That is not meaningful enough
Try to do something more with your language to make it distinct a meaningful at those different heading levels to help your users of all your readers.
Your audience, they’re not users your readers to understand these semantic differences that we think is so meaningful
Sometimes as we’re writing our content, but that meaning maybe falls away a bit, as the content is being read
You mentioned pronoun references.
This is a one that often comes up when you talk about it or that or this is it clear what it is yes what it’s what its relevant, and I had some examples there from some documentation
And I’ve seen across the scene this across different documentation again we’re very flexible in English, but other languages aren’t so flexible.
Or you need to have gender agreement, and if the pronoun is too far away from the noun that makes it tricky for the translator to decide which pronoun they need to use
So they you know if it’s a gendered language is that masculine, feminine, neuter is a plural
How do they form that pronoun, and when there’s three nouns before you get to the first pronoun, the first it you know, what is it?
That’s not as almost an existential question
What is it, if which of these nouns is it, if your writer is writing in a way where your content is going to be translated into another language, and you speak one only English, you don’t have a second language.
Is it the best way to minimize the problems for translators just to write short sentences, or are there other things they can do?
I think short sentences would be a really great start when you’re writing short sentences you’re keeping things
Also you’re keeping the sentence easy to parse, easy to understand for people at different literacy levels
And language levels again
You know you some people will be reading your English who don’t have English as a native language
So this will help them as well so short sentences, and probably the way I think of it is trying to break a lot of the rules you learnt in what we call primary school, in when you around say 8 to 11 years old assuming everyone’s school systems is roughly equivalent, which they may not be, but I can remember being challenged to expand my vocabulary and use different words, and those sorts of things.
Whereas back in technical communication, we should be having one word means one thing
If you want to talk about changing data in your software system, then always talk about changing data
Don’t say change here, modify there, alter over there.
Don’t expand your vocabulary
Shrink it back down, so that you’re very consistent very repetitive
If you find that frustrating, or you need to get out creativity in some other way, then maybe you’re one of those technical communicators who could get much enjoyment from writing fiction or other things on the side, at night or early in the mornings and let your creativity loose in that way.
It’s not I don’t believe that technical communication is it all without creativity
I think it’s a different kind of creativity to say what I imagine fiction writing would be
If I were to ever be able to write fiction it’s a different application of creativity and how we’re solving problems and communicating
So yeah, short sentences great start, and then the next thing would be my next big thing would be consistent terminology
So you also mentioned too I think I picked up on in presentation was positioning of icons in sentences. So you were saying position your icons. Don’t have them in a sentence, but have them at the end.
Yes so those were some that some I didn’t really get to go through in depth with the audience where you can have problems with icons or images in the middle of a sentence is, sometimes with your translation tools, and being able to move those image references around
Because you might need to
Obviously word order can be quite different in other languages English does have well when it comes to adjectives and how it would structure adjectives we are quite regular with that standard grammatical English but other aspects of our sentence order is quite different ways you know
I know you know German Ellis
So if we talked about German standard sentence subject verb time object manner place
So you need to if the subject wasn’t at the start of the sentence from an English sentence translated into German you need to move it around in German
And that’s just part of translation, but if you had click and then an image of an icon, you might need to move that around for the translated sentence
So you want to make sure that image reference doesn’t break
You may also need to retake that screenshot when you’ve got an OK
Well OK it’s not quite universal but I guess fairly universal in many languages
And you’d be surprised which ones do use it
But if we were translating into Russian, it would be something different than the letters O and K
In English it’s around more the translation tools – how they recognize that sentence, reuse and it might be better to consider a pop-up on hover or or something else ,or if it if we’re just talking about clicking a button
Does it really need to be embedded?
And so can you can you just say click button name, or select, depending on how device neutral you’re trying to be
Related to screenshots, do you include screenshots in your documentation, or do you avoid those as much as possible? Because that’s an area where again localization and language, different variations, just comes in
Yes in my current role you know, I’m still too new and I’m learning what’s being done and what’s the most appropriate for this software
In my previous role there was one particular piece of software that was quite a complex ERP system, with something like two thousand different screens or forms or transactions
They were also highly localizable, not just translatable, but also localizable
So depending on your configurations you know, address details would show up with postcode in Australia but ZIP code in America
You could change your tax settings for the financial functions so that again GST and Australia, VAT in the UK, sales tax in the US and so on,
So a number of and and then customers could actually make customizations according to their business processes
So a number of screens would rarely be used in exactly the way we documented them both in from a writing perspective, or if we put in a screenshot
So we kept out most of the screenshots and we also went with the premise of our audience would be reading this documentation as they’re using it there they’ve got a problem
They want to find the solution to their problem
They’re stuck at this step this is when they’re accessing content it’s not with the notion of other 200 page 500 page user manual that they’re tucked up in bed at night reading through to thoroughly understand before they go to work tomorrow
They’re going to kind of there might be training and so on happening but really going to be accessing the technical communication content we produced at the moment of need
And with the software in front of them so is the tack we took, there are different tacks taken by other writers technical communication groups. there might be times where you could have screenshots and you either keep them in English, because it’s close enough and it gives you a sense of what’s going on or you do, go to the effort of localizing them and taking all those screenshots in language.
And then hopefully if you’re going to do that, you’ve got an automated process for taking the screenshots and getting them included in your documentation, or levels of automated process to help that out.
It’s a tricky area
I’ve been working you know previously where we very much tried to avoid it a lot of screenshots due to that maintenance overhead, as well as thinking while you’re looking at the software we don’t want to be showing you so many visuals, when we think you’re looking at the software at the same time.
There might be times where judicious and deliberate use of screenshots are a good choice to make and a good choice to have effort in localizing or saying these ones really need to be localized, but these ones we think we might be able to go okay
Because we’re not doing a really translating into a really different language like a right to left language such as Hebrew, use around using flags
So there’s a few issues so some of this stems back to again years ago when I first worked with some really great localization professionals, there was some content that I was working on and the team was working on at the time and we had various localizations these were mostly statutory text based financial localizations, so it was around statutory financial reporting to meet government requirements or payroll.
Payroll is a huge localization issue.
You wouldn’t think about it
People seem to be managed to be paid in almost every country in the world but every country and sometimes you know down to state or sub-sub local areas have different rules around payroll and Taxation
So we had little flags saying you know this topic this topics for South Africa this topic is for Australia this topics for the UK and so on, and then we ended up moving away from that flag notion and putting in text there
There’s a few different problems with flags
If we want to talk about English as a language and have a flag represent a language, what flag do we use for English?
A lot of websites you might see will we’ll end up using the US flag or the UK flag, and that might be representative of their base locale, but as someone who belongs to a nation that doesn’t bear either of those flags, I’m always left a bit like well you forgot me.
I understand you don’t want to put in 20 different flags for all the different English varieties plus probably even more than 20, so it can be problematic if you’re using a flag to represent a language because a flag is not a language
And then there are issues where various countries and regions are not recognized by other regions
If you listed Taiwan as a country and the People’s Republic of China would not look on that very kindly
They do not regard Taiwan as a country it is part of the PRC
We’re to use a flag to represent the Korean language
Do you choose the North Korean flag or the South Korean flag?
So these are some of the problems around flags, but you will notice and I mention that and I’ve had had to have these discussions with developers as I try to argue for a stance of don’t use a flag to select a language
Some websites some big international websites do use flags along with the country on their websites, but that’s the key part its along with a country name
It’s not a flag as a language, and then once you get into that website like something like the Apple website, it’s a localized experience
Once I get in past that Australian flag, I’m seeing prices for products in Australian dollars, not US dollars, not pounds not Malaysian Ringgit, not anything else.
If I buy something on that website, it’s ready to ship to Australia and it’s got the the address format in the way that I expect as an Australian
I’m not being asked to you know enter a state and I’m being given a selection drop-down list of the US states
So it’s a fully localized experience for Australia
So then it’s appropriate to have your Australian flag or your British flag if you if you’re providing that fully localized experience
People can find copies of your presentation under your name on slideshare.net isn’t in your Kirsty M tailor I’ll put a link in the in the show notes for this presentation
Yes that’s correct
I think that’s all the questions at the moment.
If there’s anything else that we need to point people towards I think just the slides just the slides.
I’ve got some good references at the back of the slides as well I worked with a few you know a wide range of tech writers over the last 20 years some of whom have had strong linguistic backgrounds like I have and are happy to talk about gerunds and present participles and imperative mood and subjunctive and all these sorts of hugely grammatical terms
And some who have been really good writers, but maybe operate a bit more from a gut instinct and understanding of grammatical structures without knowing all the names so I popped a couple of references at the back
There’s a MOOC, there’s a couple of books, there’s some other presentations online that might go into areas that discuss a bit more of that grammatical terminology if you’re not familiar with it and want to read up on it.
And the other way of course is just to get people to test somebody to read your content and try it out and that can highlight things that aren’t clear absolutely
So thanks for the talk
Thanks a lot Ellis
It’s been it’s been really fun chatting with you