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.

As smartphones got smaller, the boxes got smaller too. As they became more ingrained into our daily routines, they also came with more accessories to help us out. All of this left less and less room for user documentation. Often, we had to think outside of the box to figure out how to fit everything inside the box.

The most obvious way to reduce the size of printed documentation is to reduce the amount of information in it. For both environmental and space reasons, we moved much of the smartphone documentation online. But, there were some things that we couldn’t move, such as information on where the power button was, or what gestures users needed to know to navigate the user interface and set up the phone – not to mention how to find all the information that we had removed from the printed documentation!

But, what do you do if you’ve removed all the information that you think you can and you’re still struggling to fit your documentation into a physical package? Here are a few other ways to shrink your printed documentation without impacting its usability:

• Use thinner paper. When box space is measured to tenths of a millimetre, shrinking the thickness of each page can make a difference when you add up the pages. Keep in mind that the paper still needs to be thick enough so there’s no ink bleed from one side of the paper to the other. The documentation isn’t helpful if users can’t read it.
• Reduce the font size. There is a limit to how low you can go – in limbo and in font size. But, font size is often something that you can play with. Keep your audience in mind, as products aimed at younger audiences can generally squeak by with smaller fonts than those aimed at an aging population. If you’re translating the documentation, you might not be able to reduce the font size for some languages without impacting the readability of the characters.
• Use narrower margins. If you have short paragraphs or steps, you might be able to get away with slightly smaller side margins. But, there is a limit to how tightly you can pack in the text. People need white space around the text – both between the lines and at the sides – to comfortably read it. With short paragraphs, however, the internal white space might balance out the decreased space in the margins.
• Replace text with graphics. Unlike the old adage says, you can’t often replace 1000 words with just one picture. But, you can condense short bits of information into one graphic to save space. In most cases, callouts or tables are easier for users to scan and find the information they need, rather than long paragraphs of text.
• Look at the whole package. This is where you start to think outside of the box – and the documentation. Can some information go somewhere else? For example, is there empty space on the packaging where you can put support information? Is information duplicated? If it’s on the packaging and in the documentation, can you remove it from one? Can you replace paper with another format? In our case, the smartphones shipped with blank clings on the screen and the back of the device. By moving some information out of the documentation and onto those clings, we could make better use of the space. And, better yet, the information was more visible to users.
• Take another look at the information. It never hurts to take a second (or third) pass at your content to make sure that it really is as streamlined as it can be. A good editor can help you with that task. It’s easy to get into the habit of carrying forward information because it’s always been there, without considering whether it is still necessary. A fresh set of eyes can help assess the need for content. For example, new features or emerging technology might necessitate a more detailed explanation at first. But, as it becomes mainstream, you can likely reduce that additional contextual information. Or you might be able to remove it entirely.
• The Three Cs: When you know what content needs to be included, it’s time to take a review how the content is written. Clarity, consistency, and conciseness are rules that every technical writer needs to live by. When you are working with tight spaces, they are even more important. Are there ways to tighten up the text? Have you applied plain language principles? Can you use fewer words to express the same thought?

As you can see, there are many ways to reduce the size of your documentation without reducing its usability. You might even find that making a few changes to reduce space improves the overall readability of your documentation.

If you need help fitting information into a printed format, or figuring out what to keep in the box and what to do with the rest, give Spark a call. We can help you find a solution to your space problems.

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!

To mark the occasion, we celebrated with a team lunch, taking a few minutes to think about what we’ve learned over the last year and make a resolution for the year to come.

1. Don’t panic when all of the projects come in at once!

As contractors, we are at the mercy of other people’s timelines. We can sketch out a project schedule that fits perfectly around our other projects, but if one deadline slips by a few weeks, the domino effect that it can have can wreak havoc with our stress levels.

But, we’ve learned to breathe. We remind ourselves that, with three of us, we’ve got this. We’re expert planners and have years of experience juggling projects and working to timelines. After all, our ability to load-balance between the three of us is one of the benefits of hiring us!

2. Not all business relationships are about drumming up business.

We had a great time chatting with people at September’s Communitech TechJam. We knew that most companies were looking for developers, not writers, but many companies were happy to talk with us, too. That’s what’s so great about the Waterloo tech community: everyone is supportive of local businesses, no matter what your talent is. We learned more about some of local tech companies and made some great connections. And, if those connections bring work in the future, we’ll consider that a bonus.

Outside of the tech community, we found that the small business community is just as supportive as the tech community. We sincerely enjoy the weekly WRTalk Twitter chats and the quarterly in-person meetups, where we find out more about the amazing small businesses in Waterloo Region. Without those connections, we wouldn’t have discovered businesses such as Shawerma Plus supporting Syrian refugees – not to mention discovering their awesome shawarma!

We’ve also connected with professionals in the area who can enhance what we do. When you work for a big company, it’s easy to insulate yourself within it. When you’re a contractor, there’s nowhere to hide. But there are a number of fabulous marketing, UX, and graphic design professionals in K-W. We’ve learned that it’s helpful to have a network that you can trust if work comes up that doesn’t fall within your area of expertise.

3. Know when to say no to an opportunity that isn’t right.

We love what we do and with our experience and knowledge, we know that we can help our clients. Sometimes, however, the best way to help them is to say no. That might mean saying no to the first request, but after further discussion, uncovering what they really need. We’re very good at asking questions. And, with the right questions, we can find out what the client is really trying to achieve and guide them towards a solution that will meet that need.

Rarely, saying no means saying goodbye to a potential client and pointing them in the direction of someone who is more in line with what they are looking for. But, it can happen, and we’ve learned that it isn’t the end of the world. It’s another reason to have that network of excellent contacts to point people to. It’s better to have a good relationship with a contact than a bad relationship with a client.

Our resolution: keep the awesome coming

We’re proud of the work that we’ve done for our clients and excited for the work that’s ahead of us this year. We’re busy doing what we love, with a fantastic team and a supportive network. Thanks for following along with us on our first year. With so many amazing companies in Waterloo, we know that we can keep doing what we love and having a good time while we’re at it.

There’s also a concentrated push to get more women interested in STEM. This September, the University of Waterloo announced new scholarships to help women in STEM programs. The same day, they announced a Director of Women in Computer Science position, designed to help women entering the program and to expand on the university’s existing Women in Computer Science, Women in Engineering, and Women in Science committees.

STEM is everywhere.

Now, there’s another movement that is slowing building momentum: STEAM, where the “A” highlights the important role that Arts graduates play in STEM-related fields. In July 2015, Forbes published an essay outlining how some of the most successful tech companies are recognizing the value of “useless” Arts degrees. In March 2015, the Washington Post published an opinion piece arguing that it was because of the advances in technology that society still needs Arts graduates*. The key point of these articles: innovation requires more than a knowledge of things; it requires an understanding of people’s wants and needs so that you can give it to them. An Arts education provides that human touch. Or, as Steve Jobs put it, “technology alone is not enough … it’s technology married with liberal arts, married with the humanities, that yields us the result that makes our hearts sing.”

Even the University of Waterloo, while announcing their support for women in STEM, recognizes the need for balance. They teamed up with Wilfred Laurier University and The Working Centre to create a program to highlight the important critical thinking and interpersonal skills that Arts and Humanities graduates can bring to companies within the local technology sector.

As content writers for high-tech companies, we’re happy to see people recognizing the benefits of blending arts and technology; we’ve seen those benefits first-hand. Graduates from STEM-related fields approach things very methodically. They have to. But, your average users aren’t engineers or computer whizzes. They don’t want the detailed explanation; they just want the answer. Preferably in plain language. Arts graduates play an important role in closing the divide between the detailed explanations that engineers provide, and the straightforward answers that users want.

That divide hits close to home for me. As a woman with one foot on each side of the line between STEM and the Arts, I’ve always felt a bit torn. I’m very proud of my BMath degree. I’m also proud that I use it to write. But, there are still people who see Arts degrees as “useless,” or at least subpar compared to other degrees. Putting more focus on creating STEM graduates can sometimes overshadow the impact of Arts professions and pit one against the other. The Mathie in me applauds efforts that highlight the importance of STEM, while the writer in me defends the resulting implication that Arts are not as important. It’s great to see articles shining a light on the positive contributions that Arts grads make in technology.

There’s plenty of room – and a need – for both STEM and Arts. The technology-savvy writers at Spark Content can show you how well the two complement each other.

* One minor nitpick with the Washington Post article. I would argue with this statement: “There is no way to write a six-page, narratively structured memo and not have clear thinking.” I suspect that plain language could help improve the clarity of their thinking in less than six pages. But, that’s better left for another post.

We clarify and clean up

We’re writers. It’s our thing, and we’re pretty good at it (if we do say so ourselves.) Writing isn’t just putting words to paper. It’s finding the right words to use and creating a flow that’s easy to follow. People less familiar with writing principles tend to put as much information as they can into a document to try to help users. But what seems helpful to add can ultimately hold users back.

We’re skilled at taking technical content and making it easier to read. Have a manual that feels more like a medical textbook? We can streamline it to a more manageable size. We cut through the jargon and unintentional fluff to focus on the task at hand. Your users get the answers that they need as quickly as possible.

We look at the whole picture

We call ourselves content developers for a reason. We don’t look just at the specific changes that need to be made. We consider how those changes affect your company’s broader content set. For example, can changes help offset your customer support needs? How do they align with your marketing materials? If your employees focus on one area of your business, they might not realize that making changes can impact other areas. We can make sure that the impact is positive.

We also think about translation, legal requirements, and print needs. So, when those questions come up, we already have answers for you.

We bring an outside perspective

An outside perspective means that we step back and look at the content with fresh eyes. For example, the feature that took the longest to design or code might be the most important to your project team, but it isn’t always the most important to your users. Your employees might not even realize that they are attached to certain features after their trials and tribulations with them throughout a project. We have the experience to look at all of the content objectively and align it to what your users need.

Our unique perspective also means that we’re away from the technical details – just like your customers. We ask questions about what we don’t understand, which are probably the same things that your users don’t understand. We have a good perspective on the kind of information and level of detail that a user is looking for.

We also bring with us our years of experience on other content. You benefit from the times we reworked content to fit a smaller box size or developed online help for mobile applications. Our content experience can work for you.

We make your business our business

The obvious decision of using an engineer, developer, or marketing team member to write content isn’t so obvious when you look at what a contractor can bring. Your employee might know your business already, but we make it our goal to learn your business quickly. We know how to write about products, how to get to the heart of your message, how to make sure that the message compliments and aligns with your existing content, and how to make sure that it delivers what your customers need.

Make Spark Content your content development team. With our expertise, we look at the whole picture to polish your content. At Spark, we’ve got content covered.