Writing for a global audience in tech teams

“Error rates are higher since the release” can report a time or blame a cause, and a colleague who reads it through a translation tool may get the one you did not mean. Twelve short sentences from tickets, docs and chat, checked below, each had a word like that; rewritten, none did.

This lesson shows how to write for a global audience: colleagues who read English as a second or third language, and the translation toolsmachine translation: Translation of text from one language into another by software rather than by a person, as in a browser's translate feature or a translation app. many of them use. You will replace words with two meanings by exact ones, and swap idioms and culture-bound references for plain words, with a rule pack you can run on your own sentences.

Words with two meanings: since, while, once, as and via

Google’s word list asks writers to use a few common words in one sense only. If you mean because, write because instead of since or as. If you mean after, write after instead of once. Do not use while for a contrast: write although, and keep while for time. Write “for example” instead of e.g. and “that is” instead of i.e., and do not use via at all. For a place in the text, write earlier and later rather than above and below.

Each of these words has two readings, and a translation has to pick one. Step through what happens to one incident message:

The program below runs these rules on twelve sentences and on their fixed versions. Three flags are questions rather than mistakes: “Since version 3” really means from version 3 on, “Restart the service once” really means one time, and “While you wait for the migration” really means during. Rewriting them still removes the doubt for a reader who does not know which meaning you had in mind:

// A global-reader check: words that Google's word list asks writers to avoid or to use in one sense only, run on
// twelve sentences and their fixed versions. A flag is a question for the writer, not a verdict: "since version 3"
// means "from version 3 on" and is correct, but a translator may still read "because".

const RULES = [
  [/\bsince\b/i, 'since', 'if you mean because, write because'],
  [/\bwhile\b/i, 'while', 'for a contrast, write although'],
  [/\bonce\b/i, 'once', 'if you mean after, write after'],
  [/^as\b/i, 'as', 'if you mean because, write because'],
  [/\bvia\b/i, 'via', 'write through, by or with'],
  [/\be\.g\./i, 'e.g.', 'write for example or such as'],
  [/\bi\.e\./i, 'i.e.', 'write that is'],
  [/\b(?:above|below)\b/i, 'above/below', 'for a place in the text, write earlier or later'],
];
const flagsOf = (s) => RULES.filter(([re]) => re.test(s));

const PAIRS = [
  ['Once the build passes, deploy to staging.', 'After the build passes, deploy to staging.'],
  ['Since the API changed, update the client.', 'Because the API changed, update the client.'],
  ['While the cache is fast, it is not durable.', 'Although the cache is fast, it is not durable.'],
  ['As the token expired, the request failed.', 'Because the token expired, the request failed.'],
  ['Send the logs via the support portal.', 'Send the logs through the support portal.'],
  ['Use a short-lived credential, e.g. an OIDC token.', 'Use a short-lived credential, such as an OIDC token.'],
  ['Rotate the keys, i.e. create new ones and revoke the old ones.', 'Rotate the keys: create new ones and revoke the old ones.'],
  ['See the table above for the limits.', 'See the table of limits earlier on this page.'],
  ['Since version 3, the flag is on by default.', 'From version 3 on, the flag is on by default.'],
  ['Restart the service once.', 'Restart the service one time.'],
  ['While you wait for the migration, read the release notes.', 'During the migration, read the release notes.'],
  ['The steps below need admin rights.', 'The following steps need admin rights.'],
];

let before = 0;
let after = 0;
PAIRS.forEach(([original, fixed], i) => {
  const flags = flagsOf(original);
  before += flags.length ? 1 : 0;
  after += flagsOf(fixed).length ? 1 : 0;
  for (const [, word, advice] of flags) console.log(`${String(i + 1).padStart(2)}  ${word}: ${advice}`);
  console.log(`    before: ${original}`);
  console.log(`    after:  ${fixed}`);
});
console.log(`\nFlagged: ${before} of ${PAIRS.length} sentences before, ${after} of ${PAIRS.length} after`);

 1  once: if you mean after, write after
    before: Once the build passes, deploy to staging.
    after:  After the build passes, deploy to staging.
 2  since: if you mean because, write because
    before: Since the API changed, update the client.
    after:  Because the API changed, update the client.
 3  while: for a contrast, write although
    before: While the cache is fast, it is not durable.
    after:  Although the cache is fast, it is not durable.
 4  as: if you mean because, write because
    before: As the token expired, the request failed.
    after:  Because the token expired, the request failed.
 5  via: write through, by or with
    before: Send the logs via the support portal.
    after:  Send the logs through the support portal.
 6  e.g.: write for example or such as
    before: Use a short-lived credential, e.g. an OIDC token.
    after:  Use a short-lived credential, such as an OIDC token.
 7  i.e.: write that is
    before: Rotate the keys, i.e. create new ones and revoke the old ones.
    after:  Rotate the keys: create new ones and revoke the old ones.
 8  above/below: for a place in the text, write earlier or later
    before: See the table above for the limits.
    after:  See the table of limits earlier on this page.
 9  since: if you mean because, write because
    before: Since version 3, the flag is on by default.
    after:  From version 3 on, the flag is on by default.
10  once: if you mean after, write after
    before: Restart the service once.
    after:  Restart the service one time.
11  while: for a contrast, write although
    before: While you wait for the migration, read the release notes.
    after:  During the migration, read the release notes.
12  above/below: for a place in the text, write earlier or later
    before: The steps below need admin rights.
    after:  The following steps need admin rights.

Flagged: 12 of 12 sentences before, 0 of 12 after

All twelve originals were flagged and none of the fixes were. A checker cannot know which meaning you meant, but it can find every place where a reader has to guess.

Idioms, humour and references that need a shared culture

Google’s guide for a global audience asks writers to avoid colloquialisms, idiomsidiom: A phrase whose meaning is not the sum of its words, such as "ballpark figure" for a rough estimate. Readers outside the culture that uses it, and translation tools, may take it word by word. and slang, and names three examples, ballpark figure, back burner and hang in there, as confusing and difficult to translate. It also asks writers to skip humour and to avoid seasons and other references that depend on where the reader lives: “this summer” means July in Kraków and January in São Paulo. Microsoft’s global writing tips give the same advice for idioms, colloquial expressions and culture-specific references.

Here is a chat message for a team in Bengaluru, Kraków and São Paulo, checked before and after a rewrite. The idioms marked “Google” are the guide’s examples; the others come from MySmartCoPilot’s list of phrases common in meetings:

// A team chat message checked for idioms and references that need a shared culture, before and after a rewrite for
// colleagues in Bengaluru, Krakow and Sao Paulo. The idioms marked [Google] are examples in Google's guide for a
// global audience; the others are MySmartCoPilot's list of phrases common in meetings.

const IDIOMS = [
  ['ballpark figure', 'a rough estimate', 'Google'],
  ['back burner', 'later, or not now', 'Google'],
  ['hang in there', 'say what you are thanking or asking for', 'Google'],
  ['circle back', 'discuss again, with a time', 'MySmartCoPilot'],
  ['boil the ocean', 'try to do everything at once', 'MySmartCoPilot'],
  ['low-hanging fruit', 'the quick, safe fixes', 'MySmartCoPilot'],
  ['take the rest offline', 'discuss it in a separate call', 'MySmartCoPilot'],
  ['crunch time', 'name the deadline', 'MySmartCoPilot'],
];
const TIME = [/\bEOD\b/, 'EOD', 'whose end of day? write a time and a time zone'];

function check(label, text) {
  const found = IDIOMS.filter(([phrase]) => text.toLowerCase().includes(phrase));
  const eod = TIME[0].test(text);
  console.log(`${label}: ${found.length + (eod ? 1 : 0)} flags`);
  for (const [phrase, plain, source] of found) console.log(`  "${phrase}" [${source}] -> ${plain}`);
  if (eod) console.log(`  "${TIME[1]}" -> ${TIME[2]}`);
}

const before =
  "Hi team! Let's circle back on the billing bug tomorrow. We won't boil the ocean: grab the low-hanging fruit " +
  'first and put the reporting revamp on the back burner. Can someone give me a ballpark figure for the fix by EOD? ' +
  "Let's take the rest offline. Hang in there, it's crunch time!";

const after =
  'Hi team, we will discuss the billing bug again tomorrow at 10:00 UTC. First we will fix the quick, safe issues; ' +
  'the reporting redesign waits until next month. Can someone estimate how long the fix will take, by 17:00 UTC ' +
  'today? We will discuss the other items in a separate call. Thank you for the extra work this week.';

check('Before', before);
check('After', after);

Before: 9 flags
  "ballpark figure" [Google] -> a rough estimate
  "back burner" [Google] -> later, or not now
  "hang in there" [Google] -> say what you are thanking or asking for
  "circle back" [MySmartCoPilot] -> discuss again, with a time
  "boil the ocean" [MySmartCoPilot] -> try to do everything at once
  "low-hanging fruit" [MySmartCoPilot] -> the quick, safe fixes
  "take the rest offline" [MySmartCoPilot] -> discuss it in a separate call
  "crunch time" [MySmartCoPilot] -> name the deadline
  "EOD" -> whose end of day? write a time and a time zone
After: 0 flags

The rewrite lost every idiom and the “EOD” whose end of day nobody could tell, and it gained two times with a time zone. Many of these phrases are worth understanding, because you will hear them in meetings; a later lesson of this track teaches the common ones. In writing, plain words reach every reader, and local forms of English that colleagues in one office use without thinking can stop a reader in another.

Three more habits make text easy to parse and to translate, and each has a part of its own below. Helper words such as that and then show where a clause starts, and short noun phrases show which word describes which. Abbreviations need their full form at first use. A round trip through a translation tool shows which sentences can be read two ways.

Helper words, noun stacks and only: sentences anyone can parse Pro: opens with a Pro, Premium or Ultimate pass

Abbreviations, numeronyms and pronouns, defined once Pro: opens with a Pro, Premium or Ultimate pass

Testing a text for translation: a round trip and a self-review Pro: opens with a Pro, Premium or Ultimate pass

Practise: words a translation can carry

Answer the questions below on words with two meanings and on idioms; each session opens with whichever of the two your answers show you need most:

Interview questions

Warm-up (fresher to mid-level): Why do global style guides say to avoid “since” and “while” in technical text?

Because each has two meanings and the reader, or a translation tool, has to guess which one you meant. “Since” can mean “because” or “from the time that”, and “while” can mean “although” or “during the time that”. Other languages often need different words for the two meanings, so a translation must choose, and a wrong choice changes the instruction. Google’s word list asks for “because” when you mean a cause and “although” for a contrast; for time, write “after”, “from” or “during”.

Three longer questions of this module’s bank build on this lesson:

Key takeaways

• Words with two meanings, such as since, while, once and as, force readers and translators to guess; write because, although, after or during instead.
• Avoid idioms, humour and references that need a shared culture, and write the plain meaning instead.
• A checker finds every place a reader has to guess; deciding the meaning stays with you.