Provide a list of terms that shouldn’t be translated

It might seem odd to prepare for translation by creating a list of things not to translate. But, this list can be important not only for legal reasons but also to ensure that your translated content uses terms relevant to your users. The main items to consider are product names, words or phrases that don’t have a translated equivalent, and terms that your users prefer to remain in English.

Your legal and marketing teams should be able to advise you on which product names can or should be translated to maintain your brand identity. If you have in-country technical sales members or partners, you can ask them for their insight into any technical or industry-specific terms that should remain in English.

Keep in mind that the list of terms might not be the same across all languages. Don’t assume that what is best for one language also applies to another.

Provide a list of previously translated terms that are important to you

Your translation memory, consisting of all previously translated terms, helps ensure that new translations match your existing translations. But, you might also want to keep a list of important translated terms outside of translation memory. This list gives the translators a convenient reference if they come across any inconsistencies. For example, if you have a specific way to translate a product offering, calling it out helps ensure that it’s the first option that pops into a translator’s mind.

You might also want to rely again on your in-country employees or partners to establish preferred translations for technical or industry-specific terms. Using these preferred terms avoids introducing less-desirable variations into your content.

Provide context for strings and terms

Translators are language experts, but they aren’t expert mind-readers. While the meaning of a string might be obvious to your team, you need to consider those who aren’t immersed in the product or those who don’t see the string in context.

Generally, individual sentences in documentation are considered in the context of an entire paragraph, so translators see the order in which they appear. The surrounding text becomes the context. Translators can also see whether the text is a title, if it’s in a table, or whether it’s part of a larger paragraph. These clues provide enough context so providing anything additional is usually only necessary if you’re documenting new technology or features. Sending a quick summary of the new feature and how it relates to the existing content allows translators to use consistent terminology for all related features. It can also help reduce questions that might otherwise delay the translations.

UI strings, on the other hand, tend to be incomplete sentences or short terms. They are usually arranged in the order they appear in the UI database. You might have one or two strings that come from one area of the product, but those will be preceded by strings from a completely different area. Translators can’t use the surrounding text to help them identify how the word is being used – and, therefore, what translation to apply. If a single word has multiple meanings in English, translators don’t have the necessary information to determine which translation to apply.

You can provide that context by including development comments in your strings. The comments are exported with the strings, giving translators access to this crucial contextual information. Examples of useful notes include a short sentence about what the string is referring to, a definition in the case of ambiguous terms, or information about where the string is being used. Knowing whether the string is a title, field label, or button can help ensure that your translated UI has a professional and polished look.

A little goes a long way

Providing translation instructions for important terms, along with basic context notes for strings, can greatly improve the quality of your translations and keep your projects on track. If you haven’t considered what terms should remain in English or whether there are any preferred translations for your audience, you might be missing out on branding opportunities or risking using an inappropriate translated term. And, if you don’t provide sufficient context for your UI strings, your translation project might be delayed while you provide answers to any questions from your translators. Or, you could end up with a term that is incorrect for the context where you use it.

Compiling these lists might seem daunting, but it can be done in parallel with your coding cycle so you don’t have a bottleneck at the end of the project. If you’re introducing a new product, prepare your legal counsel in advance so they can be ready to discuss product name translations. If you’re adding support for a new language, review your existing terms list and start asking if the same rules apply for the new language. And, as your developers add strings into your string database, have them add notes about how the string is used while it’s still fresh in their minds.

Whether you need help getting ready for translation, or want someone to manage the process from start to finish, Spark can help you meet your translation goals.

One thing about hiring experts – we’re thorough. We often identify changes, beyond the software, that could improve the content. Most are minor, such as updating titles to make sure that they accurately capture the user tasks or identifying wording consistency issues. But, sometimes we uncover broader issues, such as content that doesn’t address user needs or content that is missing important information. These changes take longer to address and can come as a surprise to the company, especially if they have been keeping up with smaller updates.

Here are a few reasons why a company’s documentation might not be as complete as they think that it is.

Starting with information meant for a different audience

Software projects are often under tight timelines and documentation updates are usually the last thing on the to-do list. Pressed for time, it’s easy to copy the relevant information from other project documents and make the basic changes. Some changes are easy to spot – such as turning descriptive paragraphs into numbered steps. But, others aren’t as obvious. For example, it’s harder to break away from the existing structure to look at it from the user’s perspective. So, even if the copied text is edited to make it more user-facing, the structure of the original source still dominates. Often, the source information doesn’t follow the order that users would complete the tasks in. Without seeing tasks in their natural order, it’s harder to spot what information might be missing. Other times, a single task is created, rather than splitting information into multiple tasks. Because there is so much information there, it’s hard to see what isn’t there.

Not looking at all the existing documentation

Incomplete updates are also a result of the iterative nature of software development. Because software updates usually focus on a specific part of the software, it’s tempting to narrow the focus of the documentation changes to the immediately impacted topics. Individually, the targeted updates seem reasonable and complete. But, over time, these isolated changes lead to a fragmented or inconsistent guide. By ignoring the larger documentation piece, isolated updates can overlook or exclude related information that could help users accomplish tasks more easily.

Without looking at the complete task flow in a document, isolated updates can also lead to odd workflows that jump around and confuse users. They can lead to procedures that are near-duplicates of one another, without enough information to distinguish between them. This duplication can mislead users – they don’t know which task to follow and ultimately might have them looking for information elsewhere.

Those iterative updates might be done by employees who specialize in a particular aspect of the software – and who focus on a particular content deliverable. No one is looking at the entire content set. Someone updating the user guide might not realize that there are FAQs that address the same issue. Again, duplication abounds and users are confused.

How does your documentation stack up?

Before a company updates their documentation to add new or changed features, they should take a step back and think about whether the current content addresses their users’ needs and whether it is as complete as it can be. If it’s not, they might be creating the documentation equivalent of a Jenga® tower: a large pile of information with tiny holes in it that creates an unreliable base for their users.

Because we look at documentation with fresh eyes, we are more likely to spot issues. If constraints don’t allow all changes to be made at once, we can recommend the most important ones to shore up your documentation and support your users. With our years of documentation expertise, the writers at Spark can fill those holes and make sure that you can continue building your documentation on a stable base.

It’s all about perspective

The best documentation addresses what users are trying to learn, not what the writer is trying to tell them to learn. Many developer and marketing documents tend to focus on what the writer wants the reader to know. We can’t fault them: people tend to write about what they know. Developers know how they’ve coded the user interface, so development documents tend to outline the UI elements and their options. Marketing teams want their product to sound better than the competitor, so their documents list flashy features and impressive statistics. But, both often miss out on why the user interacts with the documentation. Users don’t want to know what settings are on a screen. They want to know why they need to use those settings. And that list of flashy features loses its shine if users don’t know why those features are so great. When thinking about user documentation, it’s important to understand the user’s goal in reading the documentation.

The key is thinking about why, not just what or how

To get to the user’s goal, we ask questions. The first two are “What does this do?” and “How do you use it?” While it might seem like that’s all the information that you need, it’s missing one important piece. The what and how don’t help users without also asking the why.

If I told you how to change your phone settings so that applications closed after a set period of inactivity, what would be your incentive to use this feature? It might take you longer to open the app the next time you wanted to use it. That doesn’t sound like a useful feature and you have no reason to use it. But, what if I told you that closing your apps made your phone battery to last longer? There’s your incentive. There’s the why.

By asking questions, we find the why that users are looking for. We also sometimes uncover awkward workflows that come from forgetting the why. For example, you might have two teams who are working on two separate, but related, features, each with its own settings screen. If you focus only on the how of changing the settings for each feature, it might not be obvious if users must make changes on one screen before making changes the other. If the task done frequently, switching back and forth between the screens isn’t the best solution. Asking why a user is changing the settings reveals that it is more effective to have the settings on one screen, regardless of which team coded the features.

Writing is about anticipating what users want to know

It’s easier to write about what a product or feature does. But, it’s more effective to write about why someone would use the documentation for that product or feature. By focusing on why, you are more likely to meet their needs. And, if you can’t meet their needs, they’ll go somewhere else that can.

If you aren’t sure if your documentation is giving users what they need, the writers at Spark can help you find the right focus.

Have no fear! There are several free tools that you can use to make sure that small mistakes don’t drag down your writing when you’re crunched for time.

For this post, I considered some common consequences of quick writing – spelling and grammar mistakes, passive voice, and poor readability – and looked at the pros and cons of Microsoft Word, Grammarly, and Hemingway Editor.

A few caveats: I haven’t tried the paid versions of Grammarly or Hemingway Editor since this is about free tools, so all comments refer to the free versions. Word isn’t technically free, but since most companies already have a license for Word, there’s no additional cost to use it.

Microsoft Word

You’re probably already familiar with Word. It checks spelling as you type, or you can run the spelling and grammar checker as a separate tool. It autocorrects common typos, such as teh or adn, and you can add your own typos to the autocorrect list.

What many don’t know is that Word also has a feature that uses standard readability calculations to check how readable your text is. By looking at the length and number of words and sentences, Word can give you an idea of how easy your text is to read.

To turn on readability statistics, go to File > Options > Proofing. In the When correcting spelling and grammar in Word section, select the Show readability statistics check box.

To check your text, on the Review tab, click Spelling & Grammar. After the spelling and grammar checker runs, Word shows the readability summary.

In the Averages section, look at the Words per Sentence metric. Shorter sentences are easier to read and understand, so try to keep the number lower. An average of about 15 words or less is a reasonable length.

In the Readability section, look at the Flesch Reading Ease and Flesch-Kincaid Grade level. These show how complex your words and sentences are. A higher reading ease number and lower grade level indicate that more people will be able to understand your message. I usually aim for a reading ease above 50 and a grade level of 9 or lower.

Older versions of Word showed the number of sentences that used passive voice; newer versions don’t. If your version of Word shows it, aim for zero. Passive voice can obscure the meaning of a sentence, so it’s better if you can use active voice.

Tip: If you are having a hard time getting the Flesch Reading Ease number up or the Flesch-Kincaid Grade Level down, select and run the spelling and grammar tool on a few paragraphs at a time to figure out which paragraphs need special attention.

Grammarly

To use Grammarly, create a free account at www.grammarly.com. After you create your account, you can use the online editor or download the desktop application. You can integrate Grammarly into Microsoft Office and your Outlook email client. If you use Chrome, you can also add the Grammarly extension.

Although the premium version offers more features, Grammarly’s free version is still surprisingly robust. It looks for spelling, grammar, and punctuation errors and offers suggested changes. It also looks at sentence structure and common style errors.

Hemingway Editor

You can use the Hemingway Editor online for free at www.hemingwayapp.com or download a paid desktop version.

To use the online version, paste or type your text into their editor. It marks up the text as you go, flagging spelling errors, sentences that use passive voice or adverbs, and long sentences.

Which is the best?

None of these tools are foolproof. Word’s readability statistics are useful as an overview, but they don’t help your fix errors. Hemingway Editor flags sentences that use passive voice and complex phrases, but it can be finicky to use. Grammarly’s integrated features are handy, but I still ignore some of its “errors.”

This list of tools isn’t exhaustive – they are just three of the more common ones that I’ve tried. So, if none of these work for you, poke around and try something else. Use whatever you feel comfortable using!

If you can’t find something that works for you, or you have documents that need more in-depth review, the keen-eyed human writers at Spark are always here to help!

The content gets a bad rap – it has a reputation for being dense and confusing, with its complicated and detailed language. That language seems necessary – insurance paperwork, for example, should be specific about what is covered. But, believe it or not, even this content can be complete without being complicated.

Today is International Plain Language Day. For almost 30 years, the plain language movement has championed clear communication using clear language. The goal is to get your message across the first time that it is read. It doesn’t mean that you need to “dumb down” your content, but that you tailor your content to suit your audience.

Plain language has some obvious benefits. If users understand your content the first time that they read it, it saves them time, reduces their frustration, and builds their trust. You can avoid misunderstandings, errors, and, even costly customer support calls.

Where do you begin? Here are six strategies that you can use to apply plain language to your content:

• Understand your audience: Ask some basic questions to understand who your audience is and what they know.
• Organize your content: Focus on what’s important to the audience and omit what isn’t necessary.
• Develop your content: Keep paragraphs to a single idea and use short sentences where you can.
• Consider your tone: Be aware of the implied tone in your writing. Make sure it’s what you want.
• Consistency, clarity, and conciseness: Revise your content. Look for inconsistent wording, eliminate unnecessary words, and use words familiar to your audience.
• Use the active voice: Brush up on the difference between passive and active voice. Use the active voice when you can.

Converting your content to plain language can take planning, when you consider how much content you have. Everything from website content to social media posts to product collateral can benefit from plain language. You can phase it in over time, but you risk giving users a disjointed message. Or, you can try to time it with a particular event – a product launch or refresh, for example. That approach is better for the user, but puts a lot of pressure on writing resources.

At Spark, we’re passionate about plain language and can bring out the best in your content. With our knowledge and experience, we can take complicated consumer communications and apply these plain language principles. The end result is clear, complete content that readers can understand – without the extra complications.