Scriptorium Publishing

content strategy consulting

DITA 1.3 overview

January 26, 2015 by

Robert Anderson, one of the DITA architects, compared the transition from DITA 1.1 to DITA 1.2 to the difference between having a couple of drinks with friends and a huge party. The DITA 1.2 specification introduced broad changes in the form of new base elements, new architectural structures, and new specializations.

DITA 1.3 isn’t the rowdy gathering that DITA 1.2 was—it’s more a group of friends going out to the new pub downtown while being sure to get some designated drivers. This article describes the most important additions to DITA 1.3.

Scoped keys

In DITA 1.2, keys were always global. That is, a key could only use one value in a ditamap. If you needed a key to use two different values in different parts of a single ditamap file, you were out of luck.

DITA 1.3 addresses this problem with the @keyscope attribute. The @keyscope attribute lets you constrain the value of a key to a specific part of the ditamap. In effect, you create a local key instead of a global key. This is useful for omnibus publications or for publications that are authored by multiple teams. For example, consider a widget repair manual that describes two different products. It needs to reference the prodinfo key, but with two different values. The @keyscope attribute supports this requirement.

<map>

<title>Widget Repair Manual</title>
<topichead navtitle=”Widget A” keyscope=”Widget_A”>
<keydef keys=”prodinfo” href=”prodinfo_a.dita”/>
<topicref href=”maintenance_a.dita”/>
</topichead>
<topichead navtitle=”Widget B” keyscope=”Widget_B”>
<keydef keys=”prodinfo” href=”prodinfo_b.dita”/>
<topicref href=”maintenance_b.dita”/>
</topichead>


</map>

Before DITA 1.3, this scenario required two different keys or separate publications for each widget. To reference a key within a specific scope, append a scope to the end of the key name. For example, to explicitly reference Widget B’s product information, use prodinfo.Widget_B as the key value. If no scope is declared, the scope of the current topic is used instead.

Cross-deliverable linking

DITA 1.3 also provides support for cross-deliverable linking through scoped keys. First, you create a mapref, set the @scope attribute to peer, and then define a keyscope.

<map>

<title>Widget User Guide</title>
<mapref href=”../Repair_Manual/Repair_Manual.ditamap” scope=”peer” keyscope=”Repair_Manual”/>


</map>

Then you can use keys contained in the referenced map within the publication. In this example, topics within the Widget User Guide can use keys that are defined in Repair_Manual.ditamap. For example, to reference a task detailing the repair of a feature, an author could do the following:

<p>If replacing the module did not work, see <xref keyref=”wiring_harness.Repair_Manual”/> in <conkeyref=”title.Repair_Manual”/> for detailed instructions on how to repair the wiring harness.</p>

Branch filtering

In DITA 1.2, ditavals are global and applied when running a transform. In DITA 1.3, the <ditavalref> element allows you to specify ditavals at the map or topicref level and then cascade the filtering effects through the map. Consider a software documentation guide.

<map>

<title>App User Manual</title>
<topicref href=”prodinfo.dita”/>

          <ditavalref href=”user.ditaval”/>
<topicref href=”functions.dita”>

<ditavalref href=”mac.ditaval”/>
<ditavalref href=”windows.ditaval”/>
<ditavalref href=”linux.ditaval”/>

</topicref>


</map>

When output is generated from this map, prodinfo.dita is published using the settings in user.ditaval. In addition, functions.dita is published three times, once for each of the three ditaval files specified.

Troubleshooting

The new troubleshooting topic type is a specialization of the task topic type intended for troubleshooting steps, and consists of <condition>, <cause>, and <remedy> elements. You can use multiple cause/remedy pairs to provide a series of corrective actions for conditions that can have multiple causes.

The optional <tasktroubleshooting> and <steptroubleshooting> elements and trouble admonition type are used to provide quick, embedded troubleshooting within a topic. The DITA 1.3 specification recommends that these elements contain a condition, cause, and remedy.

The big picture

There are a lot of new toys to work with in DITA 1.3, and we haven’t even looked at some of the smaller additions, like new attributes for tables and organizational elements within topics. There are a lot of necessities to consider, but will your vendors support them, and how soon?

How could some of these new features be used to your advantage? Have you already implemented similar functionality yourself?

XML overview for executives

January 20, 2015 by

Over the past year or two, our typical XML customer has changed. Until recently, most XML publishing efforts were driven by marketing communications, technical publications, or IT, usually by a technical expert. But today’s customer is much more likely to be an executive who understands the potential business benefits of XML publishing but not the technical details. This article provides an XML overview for executives. What do you need to know before you decide to lead your organization into an XML world?

1. What is the actual problem?

What is the problem that you are solving? The answer is not “we want XML.” Why do you want XML? Are there other ways of solving the business problem? Make sure that the organization has a solid content strategy. At a minimum, the strategy document should include the following:

  • Business goals
  • A description of how the content strategy will achieve the business goals
  • High-level plan: resources, timelines, and budget
  • ROI

2. Technology is the easiest part.

As with most projects, early tool selection is appealing. It’s a concrete task, there are lots of choices, and choosing a content management system or an XML authoring tool feels like progress. Unfortunately, choosing tools too early can lead to problems downstream, when you discover that your selected toolset can’t actually meet your requirements.

Before tool selection, you should have the following:

  • A general idea of how all the moving pieces and parts will be connected (systems architecture overview)
  • Estimate of business benefits, such as $100K in yearly cost savings or faster time to global markets (four months instead of eight months)
  • A list of constraints (required/rejected operating systems, SaaS or not?, language support requirements)

3. Separation of content and formatting

You’ve probably heard this one. Storing content in XML makes it possible to deliver multiple output formats, such as HTML and PDF, from a single set of source files. This statement is true, but it glosses over a lot of hard work. Many designers are not prepared to let go of their preferred tools for building web sites or printed documents. When you separate content and formatting, you remove the designer’s ability to “tweak” their layouts. The transition from a hand-crafted page (web or print) to automatically generated pages is challenging. For some document types, the final polish you get from manual layout may not be optional. In this case, you have to think hard about what value you get from XML. You can also consider a middle ground, in which you publish into an intermediate format, do some final cleaning up, and then render the final version.

Separation of content and formatting provides for complete automation and huge cost savings, but it is not the right choice for all document types.

4. What is your organization’s capacity for change?

The best solution is the one that your organization can master. Make sure that you assess the following before making any permanent decisions:

  • Corporate culture: Is the organization typically risk-averse? Is it an early or late adopter?
  • Change management: How do employees handle change? How is change communicated? Is change resistance a common concern?
  • Leadership: Does your organization have leaders who can manage change?
  • Technical expertise: Is the solution a good fit for the technical expertise of the staff? If not, what is the plan to address this issue?
  • Executive leadership: Will executive management support this change?
  • Risk mitigation: What are the risks? What is the risk mitigation plan?

 

2015 content trends

January 12, 2015 by

It’s a new year, which means it’s time for Scriptorium to discuss—and wildly speculate about—the latest trends in content. Here’s what Bill Swallow, Gretyl Kinsey, and I had to say about 2015 content trends.

Content strategy driven by IT

dog with paw on laptop keyboard

flickr: ttarasiuk

Alan: Years ago, IT was brought in a little later in [content strategy projects], and there was also some adversarial positioning going on. I can remember one client saying, “Our IT department: they’re impossible to work with. We don’t like them.” The IT department turned out to be a really huge asset for them and really went to the mat to the help them get systems set up like they should have been.

More recently, I have seen cases where IT departments are the primary stakeholder and are the folks who are really instigating changes in content strategy because they see the overall bigger picture of how content is flowing across the company.

Gretyl: [One concern is] when your IT department is driving a project but then they are going to make a decision that works really well for them but makes things harder for content creators or doesn’t serve the organization as well as a whole.

Content as part of the customer journey

Gretyl: When someone is buying a product, they’re not just buying a product. They are buying an experience. It’s becoming a lot more important for content to be a major part of that experience of the customer journey. Marketing content will be what draws you in or educates you about the product.

And there is also some room for technical content to come into play here as well if you are looking for something that has a lot of technical information you need to know about before you can make a choice.

Bill: It seems to be a trend more on the customer side as an expectation. I think a lot of companies are really starting to pick up on this after the fact. What we’re seeing is people responding to improper information being posted online; we see a lot of complaining on social media. Pretty soon, the company is playing catch-up trying to save face.

Executive eye on content

dog wearing glasses

flickr: Monsieur Gordon

Bill: For a while now, the idea of having an executive sponsor for a major project like a content strategy implementation was fairly commonplace. But more and more, we are seeing executives who have a firm investment in the project if not direct ownership over it—so much so that we are seeing more titles out in the field for a chief content officer. [The title] was traditionally reserved for a lot of broadcasting and media companies. But now we’re seeing it in lots of different consumer companies, software, hardware, manufacturing.

Alan: There’s a stereotype out there: executives know nothing about the real world. There are some people [for which] that is true, unfortunately. They’re a little out touch with what’s going on. But I have also seen the flip side of that very vividly where an executive basically says, “I don’t need all these metrics; I don’t need all these numbers. I can tell you exactly what is wrong with this part of the big picture. I know content is part of it. Fix it.” Sometimes, they have an uncanny ability to zero in on exactly what the problem is.

Accommodating experts as content contributors

Alan: I’ve really seen an increase in content creators wanting to be sure that subject matter experts, tool experts, [and] internal experts are able to contribute content easily to the process and to review content. More and more content creation systems are allowing people to actually get into the source—and not necessarily edit the source—but to suggest edits, and someone on the content creation side can approve it.

Gretyl: This goes along with the idea of getting more and more technologically inclined. That’s really helping our content strategy both inside and outside the organization. While we’ve talked a lot before about how [technology] is helping the customer; this is the flip side of that. If you’ve got content contributors that really don’t know anything about your actual [content] creation process—they just know about the subject they’re an expert in— this is using technology to your best advantage.

Cross-company focus in content strategy implementation

Sled dogs running

flickr: Frank Kovalchek

Gretyl: For me, this a trend mostly about breaking down silos. These groups don’t interact and collaborate—and if they do interact, it’s to say, “Don’t touch my stuff.” What this leads to is content that really doesn’t work well together, and that can hold your company back. One of the ways you can get rid of this idea of silos is to develop a content strategy that encompasses all your content, and that will be more effective than just developing a content strategy, for example, for one department and ignoring all the others.

Bill: The cross-company focus is definitely on the rise, but it comes back to, “People really love their silos.” Even if they don’t, and they do want to work outside the silo, a lot of times, there is so much embedded in the way they need to work, the channels they have to go through because of financial reasons or because of reporting structures, that it is going to hinder this cross-company focused growth.

“Old” social media platforms decline

Bill: The social media landscape is going to change—it has been changing—but there are some outliers there that have been around for quite a while. Even though they still seem new to many of us, according to my kids and my kids’ friends, these are all “Mom-and-Dad networks all the old people are using.” They want nothing to do with it. They maintain a Facebook page to talk to family, but a lot of their actual interactions with friends are done on private networks, which is kind of scary.

It speaks to a different way of looking at social applications, social networking, and sharing of information. We’re not going to see a lot of Facebook, Google Plus, blogging, and other resources used by the younger generation. So, our social media and social engagement strategies around content strategy are going to need to adapt.

Alan: I think this goes back to one of the oldest and best guidelines for any kind of writing—tech comm, marcom, whatever—and that is know your audience. That’s the most important thing here. I think we’ve all seen in social media and advertising [when] companies selling fairly traditional products [are] trying to play like they’re all hip. It’s painful, absolutely painful, to see.

We had fun during the event. You can see for yourself when you watch the recording:

You’ll probably enjoy my “Did I really say that?” moments a lot more than I did!

Beneath the page: learning to see structure

January 6, 2015 by

We hear a lot about the learning curve for structured authoring, but what does that really mean?


Experienced knitters learn to read the work—they can look at a knitted object and map the knitted version to a written or charted pattern. This skill is extremely helpful in locating pattern mistakes. Beginning knitters usually can’t step outside their immediate concerns of needles, yarn, and unfamiliar motions.

Spotting a dropped stitch is easier for experienced knitters.

Reading the work // flickr: kibbles_bits

Similarly, listening to kids talk about video games is enlightening. They dissect the game, discuss the way a particular challenge is constructed, and argue about whether the various enemies are too easy or too hard. They also have an eye for game mechanics and game flow. More casual gamers (me) struggle just to figure out how to make the sword work.

Bloom’s (revised) taxonomy provides a general framework for cognitive learning:

  • Remember
  • Understand
  • Apply
  • Analyze
  • Evaluate
  • Create

You have to master the basics (remember, understand, and apply) before you can move up to the more sophisticated levels. For knitters, the analysis level is the ability to read the work. (Designing patterns is the “create” level.)

For structured content, we have a similar set of learning requirements:

  • Remember—learn basic ideas, such as elements, attributes, and hierarchy.
  • Understand—comprehend structured authoring concepts.
  • Apply—use elements and attributes as needed.
  • Analyze—look at a page (print or web) and understand how that page is constructed with elements and metadata.
  • Evaluate—assess whether a page is structured properly or develop best practices for using an existing tag set with unstructured content.
  • Create—develop your own set of elements and attributes to describe content (information architecture).

And here is the crux of the structured authoring challenge:

Structured documents require authors to gain a deeper understanding of their documents than unstructured documents. This is true even if the editing software hides elements and attributes from the author.

Just as moving from a typewriter to a word processor required additional skills, moving from a word processor to a structured document requires new skills. The software will get better and easier over time, but the cognitive leap required is permanent.

Content strategy and DITA and localization, oh my! Our best of 2014

December 29, 2014 by

Yes, you need another “best of 2014″ list to round out the year. Without further ado, here are Scriptorium’s top 2014 blog posts on content strategy, DITA, and localization.

A hierachy of content needs

Based on Maslow's hierarchy of needs, the layers are from bottom to top: available, accurate, appropriate, connected, and intelligentMaslow has his hierarchy of human needs: physiological, safety, and so on.

We have our hierarchy of content needs.

Ten mistakes for content strategists to avoid

As content strategy spreads far and wide, we are making old mistakes in new ways. Here are ten mistakes that content strategists need to avoid.

XML publishing: Is it right for you?

Wondering about a transition from desktop publishing to XML publishing for your content? Check out our new business case calculator. In five minutes, you can estimate your savings from reuse, automated formatting, and localization.

Managing DITA projects (premium)

A DITA implementation isn’t merely a matter of picking tools. Several factors, including wrangling the different groups affected by an implementation, are critical to successfully managing DITA projects (registration required).

Content strategy mistake: replicating old formatting with new tools

photo of rubber stamp

(flickr: woodleywonderworks)

When remodeling your kitchen, would you replace 1980s almond melamine cabinets with the same thing? Probably not. Then why make the content strategy mistake of using new tools to re-create the old formatting in your content?

 

XML workflow costs (premium)

Everyone wants to know how much an XML workflow is going to cost. For some reason, our prospective clients are rarely satisfied with the standard consultant answer of “It depends.” This premium post (registration required) breaks down typical XML projects at four different budget levels: less than $50,000, $150K, $500K, and more than $500K.

Content strategy burdens: cost-shifting

In assessing an organization’s requirements, it’s important to identify content strategy burdens. That is, what practices or processes impose burdens on the organization? A content strategy burden might be an external cost, such as additional translation expense, or it might be an internal cost, such as a practice in one department that imposes additional work on a different department. A key to successful content strategy is to understand how these burdens are distributed in the organization.

Three factors for evaluating localization vendors

Localizing content can be a frustrating and expensive effort. In addition to per-word costs and turnaround times, keep these three key factors in mind when choosing a vendor.

XML product literature

Maria robot from movie Metropolis

“Machine Human” Maria in Metropolis (1927)

Your industrial products become part of well-oiled machines. Unfortunately, your workflow for developing product literature may not be as well-oiled. Using desktop publishing tools (such as InDesign) to develop product literature means you spend a lot of time applying formatting, designing complex tables, and so on. This post provides three examples of how XML can improve your processes for developing product literature.

Content strategy: first steps (premium)

Content: You’re doing it wrong. That’s easy for us to say—we rarely hear from people who are happy with their content. But are you ready for a major transformation effort? Our approach is to assess the overall content lifecycle, meet with all the stakeholders, identify needs, develop a strategy, and then execute the strategy. If you want a more incremental approach, consider these inexpensive first steps (registration required).

Content strategy vs. the undead

Lego zombie hunter; image via Kenny Louie on Flickr (Creative Commons)

Flickr: Kenny Louie

Implementing a content strategy can involve overcoming many challenges. Some of these challenges can be quite scary and hazardous to your strategy. In fact, overcoming these challenges is a lot like battling the undead.

 

Localization best practices (premium)

Localization—the process of adapting content to a specific locale—is a critical requirement for global companies. More than ever, products and services are sought, purchased, and consumed in multiple language markets. Proper localization practices are critical to drive sales, and they can save you time and money in production.

This post (registration required) describes best practices for efficient, effective localization.

Scriptorium wishes you the best for 2015! Please join us on January 8 for our annual trends webcast. This popular event is free, but registration is required.

Want to solve some content problems in 2015? Contact us. We’d love to help.

Celebrating the good stuff (Blog Secret Santa)

December 24, 2014 by

Or: A stranger takes over the Scriptorium blog and gets all enthusiastic about tone of voice
Merry Christmas, Scriptorium readers. And, Sarah O’Keefe, an especially Merry Christmas to you. I’m your writer, Santa, and this is your Blog Secret Santa gift. (Everyone else: yep, hi. I’m a random stranger writing for Sarah’s blog. Because Christmas is fun.)

And here’s your present: Four websites that perform the rare magic trick of taking things that are normally really boring and making them entertaining.

How do they do this? With quality content, of course (whatever that means). Behind that, though, these four sites are all absolute masters of ‘tone of voice’. They bubble with the enthusiasm of the person behind the keyboard.

Perhaps, Sarah, your gift might actually be many hours of enjoyable reading about things like science, philosophy and cooking. Especially if you don’t mind rude words. While assembling this list I’ve discovered a personal bias towards writers who swear like sailors. Who knew?

Anyway, on we go with Santa’s Celebration Of Wonderful Tone Of Voice (Potty-mouthed Internet Edition). In alphabetical order, we salute:

1. Myths Retold

Some guy called Ovid is behind this one. He takes myths from cultures all over the world and, as promised in the blog name, retells them. His style is a mix of epic poetry and long-winded stand-up comedy. Somehow, it works.

Every now and then the ‘mythology’ ends up being an old book, too. Like the fantastic Doctor Jekyll and Mister Hyde is Really About Meth:

And for a while, shit goes back to normal

Jekyll invites everyone over for dinner parties and it’s great

but then all of a sudden he stops having parties of any kind

and in London at this time that is a SERIOUS PROBLEM

so Utterson keeps trying to go hang out

but Jekyll just keeps being like NOPE STAY AWAY

until finally Utterson gives up and is like “Welp

I guess that’s why my momma always told me never to make friends with crazy people.”

Without this site, I would never have made it to the end of Jekyll and Hyde. I don’t know if you’ve noticed this or not, but a lot of the classics are seriously boring.

2. Philosophy Bro

The most impressive thing about Philosophy Bro—possibly the finest of the internet’s many, many bros—is that he really, really knows his stuff. If you took out the foul language and streetish slang, you’d have genuine philosophical essays, and accurate summaries of many of the world’s most important philosophical works. But then again, if you took out the foul language and streetish slang, no-one would want to read it. Here’s a cut from John Locke’s ‘Second Treatise on Government’: A summary:

That’s the foundation of property – bros worked their goddamn asses off to make shit, so they had the right to that shit. An apple on a tree that no one owns is f&%$#*g useless – some bro had to pick it to eat it. Who are you to tell him he can’t eat an apple that he worked for? Yeah, I have no problem with them telling you to keep the f&@k out. Sorry I’m not sorry.

I like to think that this is actually John Locke’s first draft, and that he had a very patient editor.

3. Thug Kitchen

Ok, so with this thug‘s vocabulary he’s going to wear out his M and F keys pretty soon, but sometimes it takes a lot to get noticed. And I’m not going to get offended by the only person in the world who can make vegan cooking both hilarious and attractive. That’s right: I just said “vegan” and “hilarious” in the same sentence. You don’t get that every Christmas.

Here’s a quick, slightly-cleaned-up taster that shows you how to make people read about soy-based nonsense in between slices of bread:

WHAT THE F#@% DID YOU EAT FOR LUNCH? If it wasn’t a summer tempah sammie, take the afternoon off and re-evaluate some shit.

I discovered Thug Kitchen when the love of my life did too much yoga and got weird about food. As that spun out into a literal unhealthy obsession, I started getting pretty mad at websites that recommended cutting all sorts of stuff out of your diet for no reason. But I could never get angry at Thug Kitchen.

4. What if? (xkcd)

If you don’t already read xkcd cartoons, you’re missing out. Or you’re not a nerd. Or both. Anyway, Randall Munroe, the ex-NASA scientist behind xkcd, takes reader questions and answers them on What If? The trick is that he’s smart enough to make his answers to crazy questions sound both sciency and plausible. Like when he was asked how long humanity would survive a robot apocalypse.

What people don’t appreciate, when they picture Terminator-style automatons striding triumphantly across a mountain of human skulls, is how hard it is to keep your footing on something as unstable as a mountain of human skulls. Most humans probably couldn’t manage it, and they’ve had a lifetime of practice at walking without falling over.

I should award extra tone of voice kudos here, because unlike the first 3 sites, What If works its magic without a bunch of swearing. And that’s probably good.

So there you go. Science can be interesting. Mythology can be fun. Philosophy can be readable, and vegan cooking doesn’t have to be an over-earnest snore-fest. All it takes is something to make the content sparkle, like a perfectly worked tone of voice. If you’re struggling for traffic, you might have just found your 2015 New Year’s resolution: Sound like someone who loves what you’re writing about. Sound like yourself.

Merry Christmas!

Localization best practices (premium)

December 15, 2014 by

Localization—the process of adapting content to a specific locale—is a critical requirement for global companies. It’s often treated as a necessary evil, but this is shortsighted. The quality of localization efforts affects the company’s bottom line.

More than ever, products and services are sought, purchased, and consumed in multiple language markets. Proper localization practices are critical to drive sales, and they can save you time and money in production.

This article describes best practices for efficient, effective localization.

Your content is a business asset. It promotes your company and its offerings, drives sales, and supports customers. To ensure excellent localization, you must consider your global audiences and all aspects of content production—content development and management tools, content creation practices, and your content partners.

Use your tools wisely

Your content authoring tools and how you use them affect the efficiency and cost of the localization workflow. When choosing an authoring tool, evaluate how you will use it in localization. Every feature you use in your content will have a localization impact.

floating bird's nest

A very resourceful nest – Pixabay: Hans

Reuse carefully

Content reuse helps reduce the number of words requiring translation, but be careful. Every block of reusable content needs to be complete. Paragraph level reuse—including notes, cautions, and warnings—is ideal.

Resist the temptation to maximize reuse with minuscule chunks (sentences, phrases, or even characters). These tiny chunks do not offer the translator enough context to understand and properly translate the text. (Think of a chunk that says “green.” Should this be translated as an adjective? What noun does the adjective modify? This matters in many languages. Is it perhaps a verb or even a noun–slang for money? The translator cannot necessarily tell from the isolated chunk.)

With larger blocks of text (entire topics or groups of topics), be mindful of the amount of conditional text needed to accommodate reuse.

Conditional approval

Conditional text helps you reuse content that is similar but not quite identical in multiple locations. Use conditional text sparingly.

Heavy use of conditional text is a sign that you should reconsider your strategy. This will save your sanity in authoring the content and avoid localization problems. Conditionalize only sentences and not phrases, terms, or single words. A small tweak in English wording often leads to a major change in other languages. Your word count will be higher if you conditionalize at the sentence level (rather than inside sentences), but the translation process will be smoother.

Templates

Regardless of your choice of authoring tool, use well-designed templates with explicit paragraph and character styles. (In Word, a document that uses only the Normal style is a very, very bad sign.) A cluttered, unmanaged document will require significant reformatting after translation. Reformatting lengthens delivery time and increases overall translation effort.

Consistent template use reduces post-translation reformatting effort, as style names are retained in the translated version. You should also create copies of your templates in all target languages with appropriate customizations (for example, replacing “Chapter” in English with “Chapitre” in French). When you apply the templates to translated content, formatting changes automatically.

XML and the evils of CDATA sections

XML separates formatting from content, which can alleviate translation formatting issues. A consistent structure is imposed by XML. Styles are applied at the time of publishing and not during the authoring process. XML can also contain translation instructions, such as identifying text that should not be translated. However, the type of XML you use and how it’s implemented in your authoring tools matters.

In particular, beware of character data (CDATA) sections. Many web content management systems use CDATA within the XML. CDATA allows the author to embed HTML code inside the content. This breaks the separation of formatting and content introduced by XML, eliminates XML’s ability to enforce structure, and allows the author to inject whatever code they want. Many translation tools have trouble working with CDATA sections. The translators either need to type the markup in their translations—reducing translation memory leverage—or develop custom filters to hide this markup, which will increase your translation cost and require ongoing maintenance.

Before implementing any XML-based authoring tool, understand how it fits within a localization workflow and what the XML looks like when exported for translation. Do not use CDATA sections.

Write for translation

During translation, a translation memory file is created. This file contains all of the text strings (usually stored as complete sentences) and their translations for each target language. When you send updated content for translation, that content is compared against the translation memory to determine what has changed and how much of the existing translations can be reused.

Many translation best practices are simply good writing rules:

dove on a city railing

City dwelling birds are modifying their songs to compete with city noise – Pixabay: LollemyArtPhotography

  • Follow the style guide. Be consistent and follow your writing conventions. Small variations in the text may seem harmless (for example, “click OK” versus “click the OK button”), but they require different translations. Using a consistent writing style will increase your translation reuse, saving you time and money.
  • Avoid rewriting existing content. Avoid editing content that has already been translated unless absolutely necessary. Every change you make decreases translation reuse–and increases cost. Just adding or removing a comma reduces your translation memory leverage.

One of the best ways to avoid these and similar issues is to document your writing guidelines. Style guides help with phrasing and other writing conventions. But there are other forms of content documentation that will help you improve your content and translations over time:

  • A glossary can help you use the correct term or phrase in the correct context. With a bit of modification or enhancement, you can convert the glossary to a full terminology set for translation. It should include all of the correct terms to use (and avoid), along with their definitions and examples of use. Translate your terminology into all of your target languages to ensure that the same translation is used by all translators.
  • If you are tailoring content for a specific cultural impact, capture all custom phrases (idioms, colloquialisms, and so forth) in a document along with their meaning and intended use. Your translators may be fluent in the target languages and cultural nuances, but they may not understand your intent. This document clarifies what you are trying to communicate, and facilitates development of custom messages with the same impact in the target languages.

Share these and other supporting documents with everyone involved with your content. You can use basic spreadsheets or sophisticated applications, but in either case, you will have better control over your content and how it engages your target audiences.

It’s all about images

The adage “a picture is worth a thousand words” describes the efficiency of graphic communication, but take this expression as a warning: Every graphic you translate can cost about the same as 1,000 words. Seems high? Consider the work involved in producing these graphics, and the impact they have on the audience and your company’s image if they are misunderstood. As with written content, graphics need to be handled with care and used strategically in order to be effective.

Screen shots

Screen shots are common in software documentation and often contain the text from the user interface. Here, you face a dilemma:

  • If the interface is not translated, the translated text will be interrupted by a graphic in a language the audience may not understand. This can detract from the usefulness of your content and colors the reader’s perception of your company.
  • If the interface is translated, you must recapture the screen shots. This can be a significant effort.

If you use localized screen shots, here are some best practices:

  • Use a specific project and script for capturing all of your screens. This script should be appropriate for all of your intended audiences, and be followed in every language implementation.
  • Only include a screen shot in your content when it is absolutely necessary for communicating a concept or action, and share these graphics with your translators for their review.
  • Never use a screen shot to take up space or add visual appeal to content unless you are willing to invest the time and capital to reproduce (with modification, when necessary) this look and feel in all localized versions.

Other graphics

sign "do not feed the birds" with flying bird in a null symbol

No flying? – Flickr: Roland Tanglao

Other graphic assets come with their own localization considerations. If a graphic is paired with text (for example, diagrams or pictures with call-outs, or graphics with text flowing around them), consider how these elements should be positioned. Is it more culturally appropriate or expected that the text appear to the left or the right of the graphic? Should text be used within the graphic or not? Should the same graphic be used for every audience?

There are many other considerations when using graphics, such as:

  • Color use—red could have a positive or negative connotation depending on the audience
  • Depictions of people, including their physical appearance, situational context, and gestures
  • Symbols—a mailbox looks very different from country to country, and a flag does not correspond to a language or a specific culture

Before committing to any one graphic design, make sure it is culturally appropriate for all audiences and adapt the design to best fit what your audiences expect.

(For more details on images, check out three cost-saving tips for localizing images.)

Choose a partner, not a vendor

Your localization vendors and translators can help you make important content decisions, but some are better than others. Engage them as you would any prospective business partner. After all, you are entrusting them with one of your most important business assets.

geese preening each other

Cooperation has its benefits – Flickr: Susanne Nilsson

It may seem appealing to partner with the vendors who offer the lowest translation rates, or ones who promise the quickest turnaround times. Before making a commitment to using them, make sure that they understand your industry, the terminology and expectations of your target markets, and the types of content you plan to distribute.

Many people can translate from one language into another, but it takes special skills and knowledge to appropriately translate complex, targeted content into a specific language for people working within a specific cultural environment (which may not be their native country). Cost of translation is an important factor to consider, but a more critical factor with a greater cost is the correctness and appropriateness of the translation.

Just as you want to engage with vendors who understand your business and your audience, you want to ensure that they also understand your content infrastructure. Can they correctly and efficiently work with your source files? Does their internal workflow integrate well with your own? Are they able to work in tandem with you to develop meaningful, effective content, or do they prefer to receive files once the source development is complete? And most importantly, will they help you to identify problems early on and help make improvements, or will they simply translate your content for you?

Localizing content is something that needs to be built into your content strategy up front. It is not a tangential concern or an end-of-process consideration. If you are producing content that needs to be consumed in multiple languages or in different cultures, every aspect of content development should consider that requirement.

 

If you need help with a global content strategy, contact us today.

Content strategy for tech comm and beyond

December 9, 2014 by

Having trouble with your technical content process? Need a strategy that can help you improve and scale? Before you make a change, talk to the other content-producing groups in your company—marketing, training, sales, support—to develop a content strategy that works across the entire organization.

Work together to create a better strategy. flickr: CiRC

Work together to create a better strategy.
flickr: CiRC

The purpose of content strategy is to support your business goals. A good content strategy will save your company money by increasing efficiency in your department. A better content strategy will increase efficiency in all departments, as well as unify your organization’s content to provide a positive customer experience and strengthen your brand.

Silos form when different departments create content in a vacuum without collaborating with each other. This is a common problem at many organizations and can lead to content issues, including:

  • Two or more groups creating slightly different versions of the same content
  • A lack of branding or design consistency across company content
  • Varying levels of content quality from one group to another

Bad or inconsistent content can hurt your business. Customers drive your business’ bottom line, so focusing on the way they consume your content can help point you in the right direction as you develop a content strategy. Some ways that you can do this include:

  • Remembering that customers don’t know or care about silos—when they’re using your content, they just want answers
  • Testing your company’s content (technical, marketing, and more) as if you are a customer
  • Using other companies’ content from a customer point of view as examples for how you can improve
  • Going above and beyond delivering content that customers need and delivering content that customers want

By working together with the content-producing groups outside of tech comm, you can create a global, company-wide content strategy that improves your customer experience and helps your business grow.

For a more in-depth look at extending your content strategy beyond tech comm, check out the recording of my webcast for the Content Wrangler Virtual Summit.

Content strategy and relocation: the trauma is the same

December 1, 2014 by

We moved into a new office at the end of October. The new space is bigger and nicer than the old space, but nonetheless, the moving process was painful. As a child, I moved several times and changed schools every two or three years. I then landed in North Carolina for college and stayed put. It occurs to me that a new content strategy introduces much of the same pain as relocation.

Motive matters

Pickford's moving van

Content strategy and relocation: Not very much fun // flickr: markhillary

When you relocate or change your approach to content, the reason matters. Did you choose to move for an amazing job opportunity or spiffy new features? Were you forced to abandon your old content creation system by factors beyond your control? Did you seize the opportunity to change things? Were you involved in the decision, or was it imposed by others? Did you carefully select your new residence, or did you have to move to an undesirable location because of factors beyond your control? Did you plan your move carefully, or did you have to move on short notice? Do you consider yourself a starry-eyed immigrant to a new system or a refugee who would like someday to return to your true home?

Your opinion will be affected by your motive.

Learning a new culture

Moving, especially across national boundaries, causes culture shock. You expect big changes, such as different languages, customs, and food. But culture shock is usually caused by small things–the complete unavailability of a specific favorite food, the slight differences in how traffic lights work, the presence of near-ubiquitous connectivity (points to US), or the presence of useful public transit (all the points to Europe).

On the content side, we find similar culture shock. Typically, it falls in these categories:

  • Easy things that are hard or impossible in the new world.
  • New features that go unused because they were hard or impossible in the old world (so avoiding them is ingrained behavior).
  • Difficulty understanding the basic premise of how things work. For example, spending lots of time tracking content status in a spreadsheet instead of letting the shiny new content management system do the reporting for you.
  • Content development problems; for example, a shift from writing exclusively for print to writing for print and online media. This is a tough transition.
Learning a new culture is hard work, and it takes time. Training and education help, but exploring something in a controlled setting is quite different from living it. People need time to live into their new content systems.

Learning what’s really important

To make a successful transition, you need to understand what’s really important. Delivering great content is more important than getting to use Your Favorite Familiar Tool. Great writing skills will transcend the environment.

Before the office move, we had certain expectations for how the space would be used. In particular, we have both a conference room and an open meeting area. We expected to conduct most meetings in the conference room. But instead, the open meeting area is getting all the usage. As a result, we are rethinking our furniture in that space. Is it bad that we have a huge conference room that’s barely getting used?

When you change content processes, people will surprise you with creative solutions that are not part of the plan. It’s quite likely that some of their ideas will be better than what you had in mind, so figure out what matters (productive meetings) and what doesn’t matter (the location).

 

When we moved, we allowed ourselves at least six months to feel comfortable in the new location. For content strategy changes, expect a similar transition period.

Content strategy: first steps (premium)

November 24, 2014 by

Content: You’re doing it wrong. That’s easy for me to say—we rarely hear from people who are happy with their content. But are you ready for a major transformation effort? Our approach is to assess the overall content lifecycle, meet with all the stakeholders, identify needs, develop a strategy, and then execute the strategy. If you want a more incremental approach, consider these inexpensive first steps.

Delivery formats

Newborn fawn

Baby steps // flickr: slopjop

Are you delivering content in the format that your readers want and need? Are there delivery mechanisms that would better meet their needs? Can you implement new formats in your existing toolchain?

Many of our clients are delivering content in PDF only. A move toward HTML and especially mobile-friendly HTML can be a good first step in improving the situation for readers.

Streamlining print publishing processes

Most print-heavy environments can benefit from improvement in the print production processes. Look for opportunities in the following main areas:

  • Templates.
    Are you using templates efficiently? Your print production tool should, at a bare minimum, provide page templates and paragraph templates. Many tools go further with inline styles, table styles, object styles, and more. Building out a template that supplies correct formatting and teaching everyone to use the template can save hours and hours of production time.
  • Appearance versus reusability.
    Be careful about print-specific tweaks that damage the usability of your content in other formats. The canonical example of this is hyphenation. When reading a book on my e-reader, I often encounter words that have hyphens in the middle of a line, like this:

    Why is there a hy-phen here??

    The hyphen was almost certainly inserted into the original document to improve the line breaks in the printed document. A better solution is to use a discretionary hyphen (better print publishing programs support them). Discretionary hyphens are displayed only when a word needs to be hyphenated (occurs near the end of a line). Random hyphens scattered through the ebook are artifacts of a print-centric process.

    The content creation process needs to address appearance requirements and reusability across different formats.

Appropriate content

Are you providing the content that your readers need? You can explore this question by reviewing web analytics (if you have web content) and by examining the technical support situation. Does the tech support organization have a list of frequent problem topics? Is tech support creating additional content to address deficiencies in the technical content?

Accommodating translation requirements

If your content is translated, you can greatly improve the translation/localization process with some simple fixes to the source content. (Bill Swallow has a great article on five localization problems.) Start thinking about the following:

  • Consistent wording
  • Template-based formatting
  • Use of culturally neutral graphics
  • Technical quality of files (how are files assembled? Are language layers separate from images?)

All of these steps will improve your content without a requirement for a major strategic initiative.

Here are some things you probably cannot do without a big project (and maybe help from Scriptorium):

  • Implement intelligent content
  • Build out sophisticated reuse with metadata and a formal taxonomy
  • Reassess your tools/technologies and overall workflow
  • Get buy-in across the organization for a major content initiative