Writing for a global audience

Published on 31 March 2022 by Andrew Owen (3 minutes)

At the end of last week, I attended a conference in Budapest. I had the opportunity to give a short talk on API First, and I’ll expand on that in a future article. But one of the biggest takeaways for me was that, as an industry, we still have a long way to go in making documentation globally accessible.

If at any point this article starts to sound like an advert for the Microsoft Writing Style Guide, it’s with good reason. For most of my nearly 15 year tech-writing career, the third edition of the “Microsoft Manual of Style for Technical Publications” was the main style reference at every company I worked at. It includes an entire chapter on writing global content. I’m not sure how many people read it.

The printed book has now been replaced by a website, and updates are more frequent (there was nearly a decade between the publication of the third and fourth editions). If you write for a technical audience, I’d recommend reading the guide in its entirety.

However, if you’re short on time these are the sections that I think are most important for writers who want to promote diversity, equity and inclusion:

• Writing for all abilities
• Bias-free communication
• Global communications

To apply those lessons in my own writing, I assume my audience has English as a second language and uses a screen reader to access the text. And I have a short set of principles, in no particular order, that I try to adhere to:

• People have disabilities, they are not the disability.
• Describe only the easiest way to accomplish a task. Alternatives belong in a reference section.
• Don’t use colors to convey information. Ensure color pairs have adequate contrast. Color blindness is more common than you think.
• Images should be purely illustrative. You can use alt-text to describe the image, but it can’t contain formatted information. Text should make sense without images. Web images need alternate text to inform the reader that they are not missing any information. Images with people in them should represent diversity. Don’t use images associated with politics or religion.
• Use plain English. Make sentences as short as possible. Avoid colloquialism, slang, jargon and acronyms. If you have to use an acronym, spell it out. Use industry standard terms.
• Address the reader (you). If you have to use personal pronouns, use they/their/them (unless it’s a real person, in which case use their preferred pronouns). Use gender-neutral terms. For more guidance, refer to the Trans Journalists Association’s “Stylebook and Coverage Guide”.
• Don’t use loaded words (unconscious bias, militarism, politicized words, historical terms).
• Never use a word to mean more than one thing. Be careful with temporal terms (use once to mean one time, otherwise use after).
• Use international examples: names, places and so on.
• Don’t use Latin (avoid *e.g.; *exempli gratia, *i.e.; *id est, etc.; et cetera, via and so on).

It’s worth remembering that modern computing owes its foundations to diverse people including Alan Turing, Hedy Lamar, Mark Dean and Sophie Wilson.

Image: Original by Etienne Girardet.