Material Design and the Technical Communicator

layering (2)Material Design, Google’s design language for Android applications, has permeated both native apps like Gmail and YouTube as well as third party Android apps. Since its introduction in June of 2014, technical communicators and UX designers have explored new ways to incorporate the principles of Material Design in their workflows and products.

Material Design relies on three key principles:

  1. Material as a metaphor

The interface provides visual cues grounded in surfaces and edges that resemble those found in reality. These cues convey how objects move and exist in the visual space and react in relation to each other. For example, cards have edges and shadows, much like cards in the real world, to indicate that they are distinct from each other.

  1. Bold, graphic, and intentional elements

The elements on the screen, such as the text, space, colors, and images, convey the hierarchy, meaning, and focus of each element and provide guidance to the user. For example, the opacity of the text in the app can convey how important its information is compared to the other text on the screen and focus the user’s attention.

  1. Motion to provide meaning

All action takes place in a single environment that uses motion to transform the design and layout of the screen for different functions. For example, a settings panel can slide out from the side of the screen to provide access to settings without the app switching to a new screen.

The good news is that these principles seek to make apps more intuitive and uniform, so technical communicators won’t have to spend a lot of time teaching users how to navigate apps. The bad news is that technical communicators need to spend a lot more time testing the nonverbal cues, such as the icons, textures, and images, and verbal cues, in their app.

In most cases, tooltips and taglines are enough to teach users how to use a simple app. However, the rise of touchscreen devices has eliminated traditional tooltips, and taglines aren’t always appropriate or aesthetically pleasing. In these cases, elements like screen overlays and cards can provide instructional content in a style that matches the Material Design aesthetic. For example, you may want to provide a short series of cards as a slideshow that describes what’s new when you release a substantial update. Or, you may want to provide a tooltip overlay to describe the most important elements on the screen when users start your app for the first time.

Material Design values flexibility, so users should be free to input information without encountering too many errors. However, when an error does occur, the app should handle the error in the following way:

  1. Communicate what occurred.
  2. Provide steps to resolve the error.
  3. Preserve information already input by the user.

With the exception of the third step, this form of error handling doesn’t differ too much from the error messages patterns_errors_userinput2guidelines proposed by Microsoft. In fact, most of the
recommendations for good technical writing, such as brevity and clarity, still apply in Material Design. The only difference is the delivery method. Instead of writing a static user guide, technical writers can now incorporate their information directly into the app. For example, in the figure to the right, the red text communicates why the information entered is incorrect and how to fix it without requiring the user to refer to a separate document or leave the screen.

Mobile devices are pushing technical writers into new and exciting roles. Understanding the principles of Material Design and the iOS Human Interface Guidelines will allow technical communicators to comfortably shift from providing background documentation to providing information at a glance.

Tame Wild Writers with a Style Guide

A writer’s room without a style guide is like the wild west: cowboys making their own rules, lawlessness and grammatical errors, and gunfights at the OK corral. Alright, the last one might be a bit of a stretch, but the other points still stand. This article discusses how to bring law and order to your writer’s room through a codified manual of style. This process might not be easy, and you may have a few showdowns at high noon, but in the end you’ll end up with a functional community of writers all working towards the same goal.

Finding Support

The most essential, and perhaps hardest, part of writing a style guide is receiving support from your company. Of course, your company would love a style guide to flash to clients and keep their writers in line, but they’re not likely to schedule time that could be spent doing billable work making a style guide. So, the first step in creating a style guide is convincing your managers of its worth. Thankfully, style guides offer a number of benefits that appeal to budget-conscious managers.

First, style guides save your team time in the long run. Style guides allow writers to concentrate on the content without being distracted by having to look up documentation and grammar conventions. Furthermore, they don’t need to be extensively briefed on matters of style when taking over a project from another writer. Finally, style guides cut down on debates between writers (at least the ones concerning grammar and punctuation), which saves everyone a lot of time and a little bit of tension in the office.

Second, style guides develop a brand that your company can leverage. Many companies, including Latis Global Communications, employ multiple writers at any given time. Often, there’s no guarantee that we can assign all of the projects from as client to a single writer, so the style used for a user’s guide may not match the one used for the accompanying administration manual. In fact, even the titling conventions may differ! A comprehensive style guide, well implemented, ensures that the style and voice of the writing remains consistent throughout all of a company’s projects.

Getting Started

After you’ve convinced your boss that a style guide is a valuable tool, you face another sizable challenge: the writer’s room. Writers – whether technical or not – hold fast to their views, especially with matters of grammar and punctuation. My first time implementing a style guide, I decided no harm could come from a simple open forum among the writers to start things off. Of course, the forum quickly dissolved into a generational battle about issues such as contractions in manuals and ending sentences with prepositions, so this was not the smartest option.

Instead, you should appoint someone to act as a style sheriff. The style sheriff is responsible for writing and maintaining the style guide as well as settling disputes regarding style issues. The style sheriff should have an eye for details and a genuine interest in matters of style. Look for the writer with the most well-worn copy of Struck and White. It also helps if the sheriff is appointed by someone in charge, such as a division head or team manager, in order to avoid some of the disputes that are bound to arise with one writer dictating matters of style to the others.

As their first action, the style sheriff should choose a base style guide to inform their decisions. The most popular style guides for the IT market are the IBM Style Guide: Conventions for Writers and Editors and the Microsoft Manual of Style for Technical Publications. The former advocates a tone similar to that used in academic writing, while the latter promotes a more conversational tone. Either style guide is acceptable. However, these style guides should only inform stylistic decisions. The lengths of these style guides (389 pages and 464 pages, respectively) make them difficult to memorize for new writers. 20-30 pages is a better length for an internal style guide because new writers can easily digest it in a night and master it in a week.

Depending on your industry, you may want to consider authoring a glossary in conjunction with the style guide. The Microsoft Manual of Style for Technical Publications contains a substantial glossary of user-facing technical terms. However, you may want to use a more technical glossary, such as the IEEE Standard Glossary of Software Engineering Terminology, or even a controlled language glossary, such as glossary found in the Aerospace and Defense Simplified Technical English standard. Whichever you choose, you should treat the glossary in much the same manner as the base style guide. That is, you should incorporate entries from the base glossary into an internal glossary that contains only those entries relevant to your company in order to enhance the usability of the glossary. Tips on how to create a glossary will be covered in a future blog entry.

Lists and Meetings

After selecting a base style guide, you can start considering what to include in your internal style guide. Include too many topics, and users won’t be able to effectively memorize the style guide. Include too few topics, and users won’t be able to find the answers they need.

A good strategy when first developing your style guide is to list all of the topics covered in the base style guide. Then, armed with this list, review three or four recent projects and check off any style topics that match aspects of the project. For example, if the projects contain tables, then, naturally, you should check off the topics related to tables in your list. Finally, create a new list that includes only the checked off topics.

Distribute this list among the writers at your company, and then organize a meeting at which the writers can propose new topics. You should also allow the writers to vote on grammar and style issues that may be particularly contentious, such as ending sentences with prepositions and the use of Oxford commas. At the conclusion of the meeting (or series of meetings) you should know the topics that your style guide will contain as well as your company’s stance on most style issues.

Writing the Style Guide

After determining what your style guide will cover, you can finally start the fun part: Making decisions about grammar and punctuation. If that doesn’t sound like fun, then you may want to step down as style sheriff or risk a showdown when you can’t justify not using the Oxford comma.

Each entry in an internal style guide should state a specific rule, outline some of the exceptions to that rule, and then provide an example highlighting the rule. As in the following:

Compound Nouns

Avoid using more than three nouns when creating compound nouns. Use prepositions to clarify noun clusters.

Examples

(O) Maintenance procedure for the operator area

(X) Operator area maintenance procedure

The style guide should abide by the same formatting and style that it recommends. This allows writers to infer answers to style questions while reading, which saves time when looking up multiple issues. Furthermore, your style guide should be just as readable as any other document that you produce. So, it needs an appropriate amount of white space, pages that readers can scan easily, and an intuitive structure. Finally, formatting your style guide in this way ensures that all of your company’s internal documents, such as standard operating procedures and employee handbooks, have a consistent style and appearance.

In addition, you should author your style guide using the software most often used by your company. For example, if your company uses Microsoft Word, then you shouldn’t author your style guide in Pages. Furthermore, you shouldn’t author your style guide using a tool or markup language that is unfamiliar to members of your team. For example, if your team regularly authors documents in XML, then it wouldn’t make sense to author your style guide in Markup.

Distributing the Style Guide

After writing the style guide, determine whether your writing team would benefit most from a physical copy of the style guide, an electronic copy of the style guide, or both. If publishing the style guide electronically, select a format that uses a program openly available to your writers, such as PDF. If publishing hard copies of the style guide, consider distributing the guides in small binders so that the information can be easily updated without incurring too many additional costs.

You should then distribute the style guide in conjunction with a kickoff meeting involving all of the writers and other personnel that will use the style guide. This meeting should instruct the personnel how to effectively apply the style guide to their writing and the scope to which it applies. For example, you should specify whether the style guide applies to all documents and written correspondences or only those that the customer will see. You should also specify who will update the style guide and how personnel will be notified of such updates.

Conclusion

A good style guide can help you bring law and order to an unruly community of writers. However, implementing a style guide requires tenacity, strength, and the support of your company. It also helps if you’re organized and have a plan of action. I’ve armed you with the plan, so it’s time for you to strap on that sheriff’s badge and set the town straight.

Global Audience Analysis – A Unified Approach

From the outside, technical writing seems to only focus on the how – how to install an application on your computer, how to clean your new appliance and replace its components, how to use an API to let an app retrieve data – but, like journalists, technical writers also have to worry about the five Ws: who, what, where, when, and why. However, unlike reporters, the five Ws of technical writing are Who am I writing for?, What do they already know?, Where will they see this information?, When will this information be used?, and Why is this information important?

Answering these questions has become more difficult than ever. Audiences often include people from around the world with varying education levels, differing cultural values and sensitivities, and diverse usage environments. For these reasons, technical writers and UX designers must expand their research methods to include audiences from around the world. They must then use profiling techniques to approach their writing with these audiences in mind. This post introduces a holistic approach to research that combines top-down, bottom-up, and audience profiling to ensure that you and your writing team have all of the information required to reach your audience at your fingertips.

Top-down research

A good starting point for analyzing your audience is to use existing internal sources, such as your company’s marketing and sales teams, the analytics for your company site, and community forums for existing products. These resources help you identify the type of people that you’ll be writing for and the information that they’ll be interested in.

Your first stop should be the sales and marketing teams. These teams can provide a wide range of high-level information. Your sales team can provide ample information about existing clients and users, such as statistics on current users. In addition to this, the marketing team amasses large amounts of market research about the target demographic, that is, the users, of your product or service. These teams may even produce internal case studies detailing specific examples of customers using your product.

Your sales and marketing teams should be able to provide the following general information about your audience:

  • Gender
  • Age
  • Education level
  • Monthly and annual income
  • Occupation/profession
  • Marital status
  • Nationality
  • Social class
  • Population size
  • Region

This demographic information offers a tremendous amount of insight into your audience. However, it only addresses the first two Ws: Who am I writing for? and What do they already know? This information is invaluable, but addressing the other three Ws requires bottom-up analysis in the form of focus groups, surveys, and support system reviews.

Bottom-up research

Your top-down research provides you with a general idea of who will be using your documentation. However, a bottom-up analysis – that is, an analysis that includes information gathered directly from your audience – is necessary to establish where your audience will see the information, when they will seek out this information, and why they sought this information in the first place. In most cases, a bottom-up analysis takes the form of focus group interviews, user surveys, and reviews of support system information or a combination of these three tactics.

Focus group interviews can provide deep insight into how and why your audience uses your product or service. However, they are also the most expensive method of finding out about your audience. Often, a good idea is to piggyback on a focus group convened by the sales or marketing teams in your company, as your audience will also be their target demographic.

Your focus group should include people that fit the demographic profile identified in your top-level analysis. When you’re writing for a global audience, this means that you may need to conduct multiple focus group sessions in various countries. This can be a costly, but beneficial, exercise, especially when entering a new market abroad. However, if the cost is too great, then you should strive to assemble a multicultural focus group within your own country.

Focus groups can help you gain more insight into the following:

  • Where users use documentation
  • What motivates your users to use your documentation
  • Why users use (or don’t use) your documentation

User surveys are another method of finding out about your audience. Although not as costly as focus group interviews, user surveys still require a certain amount of upfront investment in their creation and a lot of work to tease out relevant results from the mountain of data that you accumulate. Furthermore, user surveys tend to add a filter to your audience – that is, only a certain portion of your demographic is likely to fill out a survey.

The value of surveys, however, is that they are relatively inexpensive to administer compared to focus groups and allow you to compile answers to targeted questions comparatively quickly. The survey method you use largely depends on how established your company is in the target region. If you already have existing customers or clients in the target region, then they may be willing to fill out a short survey. If your products have generated some interest in the region, then adding a call to action that directs visitors to your website may be the way to go. Finally, if your brand is new to the region, then you may want to consider hiring a market research company to make sure that your survey reaches your target demographic.

Users surveys can help you answer the following:

  • Where users use the product or documentation
  • When users use the product or documentation
  • Who do the users trust for information

Finally, support systems, such as Zendesk, or even sales sites that feature reviews, such as Amazon, allow you to gain some insight into how your audience uses your product and the aspects of your product that they find most troublesome. Like user surveys, support system research requires a substantial investment in labor and only the portion of your audience predisposed to making comments will do so. Nevertheless, a support system review offers the quickest way to receive direct input from users regarding the success or failure of your documentation.

Because the content focuses on the problems users encounter, support system reviews offer only a limited window through which to get to know your audience. But, as a technical writer, you strive to minimize these problems, so support systems provide excellent insight into when and where your audience requires information as well as the features that they need the most information about. Although valuable, this information is insufficient to create an audience profile, so a support system review should be supplemented by one of the other methods of bottom-up analysis.

Audience Profiles

The information gathered from your top-down and bottom-up analysis is invaluable, but you undoubtedly have mountains of it. Staring at spreadsheets full of demographic information, survey responses, and customer complaints quickly gets boring. To combat this, writers use audience profiles to put a real face on their audience.

Audience profiles, sometimes referred to as reader profiles, compile your top-down and bottom-up research into digestible descriptions of audience members. These profiles usually take the form of a narrative, but a CV-inspired style is also popular. Less popular, but still effective, is the collage-style audience profile.

Narrative profiles leverage what you already do well – write – to describe an audience members in a manner similar to that found in narrative prose. Many writers perform similar exercises when coming up for characters for fiction. Narrative profiles often contain greater detail and provide a more natural way to read than the CV or collage models. However, narrative profiles are also more difficult to scan, so you may find yourself rereading the same description over and over to confirm details as you write. For this reason, narrative profiles often include a photograph of the fictional audience members procured from a stock image site.

CV-style profiles allow you to easily locate important information at the expense of readability. These profiles consist of bullet points grouped under various headings, such as work experience, family life, and hobbies and interests. Like narrative profiles, CV-style profiles often include a picture so that the writer can identify with the face of the audience. The bullet points allow you to quickly scan the page for relevant information when writing. However, because the information is segmented in bullet points, it may be more difficult to paint a portrait of the audience member in your mind’s eye when reading the profile.

Collage-style profiles have fallen out of favor in professional writing, perhaps because they make your cubicle resemble a teenager’s bedroom, but they can still be as effective as the other profile methods. A collage profile usually consists of pictures of the fictional audience member and items related to their profession, interests, hobbies, and family. For example, a profile of an audience member may include pictures of schematic drawings, the Indiana Colts playing football, wakeboarding, and young children. These images may be supplemented by quotes from the audience member, such as “Why can’t they just print the instructions on the damned thing.” Collage profiles offer writers a refreshing break from reading and writing but require the writer to recall the motivation for including a picture or quote when writing it and require substantial explanation when handing off the project to another writer.

Conclusion

Whichever profile style you decide on, you’ll probably want to create at least one profile for each target country so that, as you write, you can ask yourself “Would Pornchai from Thailand find this easy to read?” or “Would Samadhi from Sri Lanka look for this information here?” In short, you can try to approach your writing through the eyes of your audience. Doing so will greatly increase the effectiveness of your writing and add a necessary direction to your voice. But remember, a good profile requires the right kind of research, so the top-down and bottom-up research steps are incredibly important. Performing all of the tasks described in this post with the end goal in mind will ensure that your text is accessible to your entire audience.

 

 

Five Ways to Prepare your Software for Localization

Today’s tech market encompasses far more than just North America and Europe. Emerging economies in South America, Asia, and Africa have changed the landscape of both software development and sales, and consumers now expect and demand products and services tailored to their linguistic and cultural needs. Failure to meet these needs harms the competitiveness of your product and, in many cases, allows other companies to clone your product and reap the customers you deserve.

Proper localization helps your product fulfill these needs. However, localization involves more than just hiring a good translation company – it involves thorough planning throughout the development cycle of your product, careful consideration of design elements, and a concerted effort from the entire development team. The following five tips will help you keep your localization efforts on track and ensure that the process is as painless as possible.

Start early

Start preparing to localize your product as soon as you identify its core features and target markets. Even if you haven’t clearly identified where you plan to release the product, it’s still a good idea to ensure that the development and design teams consider localization when creating the user interface. For example, text in other languages may be up to 50% longer or shorter when translated, so elements such as text boxes, dialog windows, and menus should be sized to accommodate both the longest and shortest strings in this spectrum.

Leaving the localization process until the last minute may also lengthen your development time and localization costs. Whether you’re using an agile or waterfall workflow, a good localization partner can work with your schedule to provide incremental support for text translation and localization. In fact, involving a localization company early in the development process often improves the end result because the company has time to get to know your team and understand your product. In addition, many localization companies charge a premium – sometimes even double the cost – for quick turnaround times and same day service. So, if you wait until your product is finished before beginning the localization process, then your project may come in past the deadline and over budget.

Develop your own style

After all the time invested into developing the focus and feel of your product, there’s no reason that the text in your software shouldn’t also convey these attributes. Issues such as inconsistent capitalization or syntax can be distracting to users and may even cause them to misunderstand the content. To achieve a uniform style throughout your software, you need to outline the rules governing things like capitalization and syntax choice in a style guide.

Luckily, many of the rules outlined in a style guide can be applied to multiple languages. Some languages may render certain rules moot, for example, languages such as Korean, Japanese, and Chinese do not require capitalization guidelines. When you initially consult a localization provider, confirm that they have the resources necessary to create style guides for all of your target languages.

In addition to text, designers must also consider the icons and images to ensure cultural sensitivity and relevance. For example, some user may not be comfortable with excessive flesh or be familiar with the mailboxes used in North America. This comes with a slight caveat. Accepted icons such as the hamburger icon and save icon have achieved cross-cultural relevance, so these and other similar icons may be used.

Format and isolate text

You should ensure that all text strings use Unicode character encoding. Unicode allows the easiest transfer into languages that don’t use Roman characters, and it handles most of the world’s writing systems. Implementing Unicode after writing the code is a difficult and time consuming task, so it’s a good idea to establish this in your programming best practices before you write the first line of code. In the rare instance that the product cannot support Unicode, then you may need to find a work around using DBCS enabling, bi-directional (BiDi) enabling, code page switching, or text tagging.

In addition to using Unicode encoding, you should also isolate all target text strings from the source code of the project. Programmers should place all target strings in resource files, message files, or a private database. However, these resource files should not include any strings that will not be localized. Any strings that do not require localization should remain as string constants in the source code. Isolating the localization strings in this way ensures that all text is localized according to your company’s style guidelines and allows your software to transition between languages more easily.

Minimize formatting issues

When creating your software, you should consider the range of formatting issues that may arise due to differences in the conventions used for information such as addresses, currency, dates, and telephone numbers. To improve usability, the input fields in which users enter this kind of information need to accommodate various input lengths and characters. For example, postal codes in Canada are a mixture of six letters and numbers, whereas those in the United States use only five numbers. Thus, an input field in a product intended for both countries must either accommodate the relevant lengths and character types in its validity check or separate input fields must be provided. Implementing such changes after releasing the software requires extra investment in development and bug testing and may require resources, such as the original programmer, that are no longer available.

Developers must also consider formatting when writing routines. Some countries, such as Japan, use district and block divisions in addresses rather than street numbers. In software released in such countries, any routine that parses addresses for storage in a database or printing on shipping labels must be able to process such addresses. Failure to do so may result in extra costs from shipping goods to incorrect addresses or customers who are unhappy due to receiving late shipments.

Reuse help content

Help content, whether in the form of tooltips, API documentation, or an old fashion manual, is integral to make your product easy to use and ensure early adopters are satisfied with their experience. However, help content can also quickly consume your localization budget if improperly managed. Most localization vendors charge by the word, so localizing complex sentences and redundant information costs far more than the information may be worth. Keep help content simple and short to get the most return on your localization investment.

In addition, most localization companies charge only for the first time a string is translated. So, whenever possible, developers should strive to recycle strings in order to increase information availability without increasing localization costs. For example, the sentence that introduces a feature in the manual can be used as the tooltip that appears when a user hovers over the icon for that feature, and the section from the manual can be reused in the web help. In essence, this allows you to provide help content in three places for the price of one without adversely affecting the information conveyed by the help content.

Implementing these five simple guidelines during the development of your software vastly decreases the timeframe and cost of localizing your software. Starting early and incorporating these guidelines also ensures that you deliver the best possible product to every target market. For more information about preparing your software for localization, consult the Microsoft Developer Network or your localization provider.