As a technical writer in a SaaS company, you already know that nations’ borders don’t confine your work.
Most SaaS companies offer their services globally, meaning that technical writers should keep in mind that their text will get translated into many different languages.
To make that process more manageable for your organization and the translators who’ll get to work with your documents, you can take certain steps from the very beginning of your writing task.
In this article, we’ll share some helpful tips on how to write for easier translation. Let’s start!
Use Concise Language
When you’re writing technical documentation, and you know that someone is going to translate it, your goal is to make that task simpler for them.
How can you accomplish that? We will examine several ways to do that, but the first thing you can do is use clear and concise language.
That means you simplify your vocabulary and use precise grammar and clear phrasing. As a technical writer, those are most likely rules you write by anyway, but they’re even more important if you want to make it easier for translators.
A language we just described has its own term—plain language. Here’s how the late Robert Eagleson, an English professor and a big proponent of plain language, defined it.
How does that contribute to translation?
It’s simple—a document with precise vocabulary, common words, and straightforward structure is more consistent and better organized throughout, making the translation process more manageable.
Let’s look at an example of technical documentation that uses concise language well.
Canva, an online graphic design platform, has a rich help center that covers many topics and issues.
One of the articles provides instructions to users about how to download designs they make as videos or GIFs.
As you can see below, the instructions are written in a very straightforward way, they’re brief, and it’s virtually impossible to misinterpret them.
Also, notice how the writer used the same terms for the same actions.
For example, they used only download and not save, transfer, move, or some other term that would fit the context.
Similarly, it’s always design, and not project, image, or composition.
Not only does that make the experience of using the documentation better for users, but it also makes it better for translators—it saves them time and unnecessary hassle.
Create a Glossary
As a technical writer, one of the things you always have in the back of your mind is that you shouldn’t assume your reader’s level of knowledge.
Sure, you might be an expert in API documentation, but your reader doesn’t have to be. The same principle applies to translators, too.
Their level of expertise in the field you’re writing about isn’t necessarily on par with yours or even high at all. That’s why you should provide them with as much additional information as you can.
A glossary is an excellent tool for that. Here’s how technical writer Kesi Parker explains it:
For most technical documentation, a glossary is very helpful.
A writer simply cannot explain and define every technical term in the text itself—that would make it filled with definitions and challenging to read.
For instance, Amazon Web Services has a glossary containing hundreds of terms in alphabetical order.
There is no real alternative to it—either all of those terms would be defined in the documentation, or they wouldn’t be defined at all.
The latter would be particularly detrimental to translations. As we mentioned, you can’t expect translators to know every technical term.
With glossaries like the one from Amazon above, translators can quickly clear up any terminology-related issues they might have while translating.
Of course, a glossary is useful even if it’s not as extensive as Amazon’s.
For example, ChartHop has one as a part of its documentation created with Archbee, our own documentation platform.
For translators, it can be very valuable because, when it comes to technical documentation, there are terms that have different meanings in different contexts.
Let’s use ChartHop’s glossary to illustrate that.
For instance, we all know what a scenario means—but does the translator instinctively understand what a scenario is as a part of ChartHop’s terminology? Not if he or she can’t find a definition of it.
Luckily, they included it in their glossary:
Therefore, a glossary with technical terms like that can clear up the confusion and provide translators with essential information about the product or service.
Without that, there could be mistakes, and mistakes can be costly.
Write With Localization in Mind
When you write technical documentation, you should be aware that your readers could be very different from one another.
And we don’t only mean by their level of expertise, professional background, or interests—their language and culture are also vital factors to keep in mind.
That’s why you should keep your writing simple and not rely on using elements like jargon, humor, or cultural references.
For example, below, you can see a video from Google Help about search tips, done entirely in the form of a rap song.
It’s clear that its ambition is to be informative and humorous. Still, localizing that type of content is difficult—different cultures have different ideas of what’s funny, and the nuance of intentionally bad rapping could easily be lost in translation.
Here’s another example of humor in technical writing.
It’s a part of a table of contents from a user manual of a 3D rendering software.
As you can see, the authors took a lighthearted approach, which they probably deemed acceptable for their target audience.
However, a translator could run into problems when trying to localize expressions like “Puttin’ this puppy on your unit” or “What the #@&?% is going on?”. A word-for-word translation doesn’t work in situations like this, and the translator would probably struggle to find a phrase that fits in his or her language.
In addition to humor, you should also consider abbreviations while writing with localization in mind.
Some abbreviations are so standard in every language and culture that there’s no need to define them and, therefore, to translate them.
For example, writers of IBM product documentation don’t need to define that the abbreviation stands for International Business Machines, and translators don’t have to worry about localizing it.
On the other hand, an abbreviation like MFA (multifactor authentication) isn’t that commonly used in different languages.
Therefore, technical writers should define it, and translators usually translate it.
To sum up, different nations and cultures have many distinctions, and it’s impossible to know them all.
That’s why avoiding pitfalls we mentioned in this section can go a long way.
Keep Text Separate From Graphics
Visuals in technical writing can make the difference between a boring set of instructions and an engaging technical document.
And as a technical writer, you undoubtedly aim to create the latter—the readers certainly prefer it, and the data indicates that they learn more efficiently when visuals are included.
Therefore, graphics are something that you shouldn’t overlook.
However, if you know that your documentation will end up on the translator’s table, you should ensure that visuals don’t overcomplicate their job.
Luckily, that’s easy to do—just keep your visuals and the accompanying text separate.
That way, a translator can access and translate the text while leaving the graphics intact. Otherwise, the graphic would have to be created from scratch to include text in a different language, wasting valuable time and resources.
For instance, take a look at the example below:
As you can see, the writer kept the visual separate from the explanatory text by using a callout—a text that points to a specific area to describe or explain it.
Here’s another example from technical documentation that uses photographs and text which explain the steps to perform the actions depicted in those photographs:
The same principle applies to any type of technical documentation and in any industry.
For instance, if you’re a Windows user, you might come across one of the manuals for Windows 10.
Visuals are very prevalent here. Screenshots illustrate various features of the software while the text is separate.
For a translator, that’s an ideal situation—they don’t need to worry about editing the screenshots, so they can focus on the text they need to translate.
Therefore, keeping text and graphics separate is a step you shouldn’t overlook when creating technical documentation.
Otherwise, the translation process could be much more demanding.
Carefully Select Fonts
As you have probably noticed by now, many elements can significantly determine what will the translator’s experience be like with your technical documentation.
In addition to carefully adapting the language, choosing the terms you use, and making design decisions, there is also the element of choosing fonts.
And while at a glance, that might seem like a minor decision that comes down to personal preference, it isn’t—not all fonts are universal for all languages.
For example, take a look at Adobe’s Software License Agreement below. As you can see, there was a problem with the font in the drop-down menu.
The characters that are pointed out are called tofu boxes. In short, they are empty squares that show up when a font doesn’t support a language, in this case, Korean.
Choosing a font that is suitable for all languages your documentation is going to be translated into can prevent problems like that.
With that in mind, Google developed Noto Fonts.
It’s a collection of various fonts suitable for communication in more than a thousand languages.
You can filter them by continent, region, script, and language, so it’s easy to find a font that suits your needs.
In other words, Noto Fonts are very useful in writing technical documents for translation.
Of course, there are other ways to select an appropriate font. You can find helpful lists online which tell you what font to use for what language, like the one from Diplomatic Language Services.
Carefully selecting fonts is undoubtedly one of the necessary factors for a successful translation.
Without a font compatible with a language, a translator could do a fantastic job—and no one will be able even to see it. So, don’t underestimate the importance of this step.
Allow For Text Expansion
In an ideal world, a technical document would look identical when translated into any language.
Every heading and subheading would be on the same page, every bulleted or numbered list would fit in the same place, and every visual would be exactly in the same place in the document.
However, the reality isn’t like that—the simple fact is that one text written in different languages won’t take the same amount of space.
There is data that supports that. According to A Practical Guide to Localization, some languages can take up to one-third more space than English—for example, German or French.
In other words, your text and all the elements you so carefully crafted in your documentation could look very different when translated into a different language.
A Practical Guide to Localization suggests several methods of handling that possible text expansion:
- Add pages to the translated version
- Decrease font size
- Change spacing
- Change page margins
- Instruct translators to maintain one-to-one page correspondence
Luckily, if you write and maintain your technical documentation in Archbee, you have a built-in feature called Localization that makes text expansion more manageable for everyone involved in the translation process.
With this feature, Archbee translates every user interface element on top of the content you create in English.
It’s also worth noting that when you use a solution like Archbee, you don’t have to worry about fitting elements onto a page. There is no limit to the number of words, and a word count feature can help you see the changes in text expansion more precisely.
To summarize, taking text expansion into consideration when creating a technical document can help make the translation process easier.
Reorganizing elements can take a lot of time and effort, which could be spent on more important tasks.
Conclusion
Technical writers have a lot of responsibilities and tasks in their day-to-day work—there’s no question about that.
However, whenever possible, they should also include writing and preparing their technical documentation for translation.
Successful translations can bring only benefits to the company - more satisfied customers, a bigger market for products and services, and, of course, more profit.
And the way the writer creates their document can be an excellent foundation for a successful translation. We hope we’ve inspired you to take that process in the right direction.
‍
