Scriptorium Publishing

content strategy consulting

Structured authoring: breaking the WYSIWYG habit

July 28, 2015 by

There are many challenges involved when moving to structured authoring (XML), but perhaps the most personal challenge is breaking out of the WYSIWYG (what you see is what you get) authoring mode.

The rise of desktop publishing has merged the roles of writer, editor, designer, and publisher into one. With many modern authoring tools, what you see in the authoring environment and what you get as a finished product is nearly identical. It’s easy to settle into a WYSIWYG mindset, as there’s comfort in knowing what the content will look like. However, that trust can be misplaced.

WYSIWYG authoring works best under one condition: producing one type of document with a very specific design. Once you add another format into the scenario, the model begins to fall apart. If you’re supporting two or more delivery formats, you end up designing for one and hoping that it looks good in the others. Juggling several different formats, perhaps with content reuse between them, can quickly become tedious.

A move to XML involves removing the physical formatting of content from the words themselves. Instead of manually formatting text as “Times 18pt Bold” or applying a specific “Heading1″ style to text, you encapsulate the text within a tag (<title>, for example). This tag can then be rendered however you prefer for any output format, at any heading level. This has many advantages in multi-output scenarios, but because the formatting is detached from the content itself, it can lead to frustration among visual authors.

Some XML authoring tools provide both a text view and a visual markup mode as you write. The markup mode does provide some level of visual formatting, but it’s anything but WYSIWYG. Be careful not to mistake the visual authoring mode as an indication of what the final output will look like. It’s best to divorce yourself of the WYSIWYG mindset when transitioning to XML authoring.

Here are some tips that can help you break bad WYSIWYG authoring habits.

Remind yourself of the big picture

Always remember that the content you are writing could be used anywhere. It could be in a printed book or PDF, or on a web page, or on a phone. Because these are very different delivery mediums, you cannot visually format text for all of them at once (at least not well).

Instead, trust not in what you see but in your publishing process. The transformations that produce your finished products from the XML will format the content appropriately, provided the XML has been correctly tagged and structured. In the case of the <title> example mentioned earlier, it can be formatted in a different way in each target output—using different fonts, weights, colors, or other stylistic treatments.

Try working in text mode

Switching from WYSIWYG authoring to text-based authoring (think Notepad) can be a very difficult transition for some people (if not downright scary), but there is value in seeing and understanding what is going on “under the hood” with your content. Seeing that something looks bold doesn’t necessarily mean it’s arbitrarily formatted that way. It could mean that it’s a UI label, or a special term, or some other specific type of content. As an author, it’s very important to know the difference and to use the correct tag.

When you first begin working with XML, take some time to try writing in both interfaces (text mode and visual mode). Switch back and forth, applying tags in the visual editor for a bit, and then hand-typing them in text mode. Do this until you become comfortable with the correlation of what you see in the visual editor and the tags (in text mode) that they represent. This will not only break you of the WYSIWYG authoring mindset; it will prepare you for any structural troubleshooting you may need to perform on content down the road.

Get uncomfortable

Developing content, like exercise, is habit-forming. The more you do it, the easier it gets, but the more you conform to a particular technique. In the case of exercise, it could mean that you begin to overstimulate some muscles and underutilize others, despite enjoying the activity and its benefits. When developing content, the more you approach it using the same tools in the same manner, the easier it is to form habits along the way. These habits may get the job done well, and you may enjoy the way you work, but WYSIWYG habits won’t transition well into structured authoring.

yoga pose

image: Pixabay//SimonaR

If you’re coming from a WYSIWYG background, you may have some habits to break. While the tips mentioned earlier will help, the key is to allow yourself to get uncomfortable and stop authoring the way you used to.

XML authoring is not at all like WYSIWYG authoring, and no authoring UI will change that. As close to WYSIWYG as some visual authoring tools may get, the underlying content is still XML, and it needs to be semantically and structurally correct.

If you find yourself struggling to change, push yourself further. Work only in text mode for a while, or switch between text and visual authoring modes more frequently. Just as it is difficult to train a different set of muscles when exercising, making an authoring transition can be difficult. But with time and dedication, you’ll reap the benefits.

Announcing free DITA training

July 22, 2015 by

Our new DITA learning site, is now live with its first course, Introduction to DITA. logo

We put a bird in the logo. Imagine that!

Are you somebody who is interested in DITA, but not sure that it’s right for you? now provides a free Introduction to DITA that you can work through on your own time.

The content was developed by Scriptorium staff and other contributors using an open-source DITA training project hosted at GitHub.

The course includes six lessons:

  1. What is DITA?
  2. DITA topics
  3. Metadata
  4. Creating DITA content
  5. Tables
  6. Creating relationships among topics

Lessons include code samples, links to additional resources and videos, and more. There is a quiz at the end of each lesson.

We hope this site will become a useful resource for the DITA community. We welcome additional content through the GitHub repository. We’d like to expand the introductory content and offer more courses with advanced topics, but we need your help to do that. If you’re interested, check out the project roadmap and start writing!

Thanks to content contributors (listed in each course topic) and to the site’s sponsors.

P.S. To get notifications about new content on the site, sign up for announcements. You can also sign up during the site registration process.

Localization: are you the weakest link?

July 13, 2015 by

There is an old proverb that says, “a chain is only as strong as its weakest link.” While many of the links in the chain could be quite strong, it only takes one weak link to break the chain. There is one process chain in particular where this proverb rings true: localization. However, more often than not, little or nothing is done to identify and strengthen the weakest link in that process.

When it comes to localization, there’s a common misperception that if there is a problem with the translation then the vendor is to blame. In some cases this may be true, but in every localization effort (no matter how large or small) there is a shared responsibility between content authors and translators to ensure that the translation is accurate and is completed both on time and within budget.

localization chain

If any link in the localization chain breaks, the chain itself fails. Half of these links are owned by content development.

If we look at every link in the localization chain, we can start to see where the possible failure points may be.

What content creators control

Style guide: A corporate style guide defines how all content should be developed and presented, from writing style to publishing standards. If the rules in your style guide are ambiguous (or worse, if you don’t have one at all), your entire content development effort is left to chance. A good style guide should inform both the source language content development effort as well as the localization effort. In short, it’s the single source of truth for developing all of your content, in all languages, for all audiences.

Terminology: Just as a style guide informs how to develop content, a terminology reference (repository, term bank, master glossary, etc.) informs which words are correct to use, in which contexts they can be used, what they mean, and (perhaps most important) which words never to use in their place. A good terminology reference can prevent unintentional misinformation, and can and should be localized on its own so all terms are properly defined for each target language. Leaving terminology to chance can lead to perfectly cromulent results.

Quality of writing: Writing quality plays a very large role in translation quality. If the wording is unclear, or if the same concepts are written in different ways, then translators may misinterpret how to translate the content. Consistency in writing is critical; a formal editorial review can enforce consistency. Even with a style guide in place, it’s easy for writers to become out of sync without an editorial review.

Consistent formatting: Regardless of what tools you use to author your content, consistent formatting can significantly reduce translation turnaround time and cost. If your tools use templates, adhere to them 100% of the time, and provide the templates to your localization vendors (they should be reviewed for localization appropriateness and modified as needed for target languages). Whoever formats the translated content can then apply the localized template and avoid hand-formatting, provided authors haven’t used formatting overrides.

What localization vendors control

Translation workflow: The translation vendor should have a system in place to manage the overall translation effort. These systems track which translators are being used, which content they are responsible for, and all of the checks and balances between starting and finishing the translation work. Lack of such a system, or a breakdown in this communication chain, can cause deadlines to slip and costs to rise.

Translator qualifications: Translating content requires more than just a strong command of the source and target languages. A good translator must also be familiar with the subject matter, and be very familiar with the regional variations of the target language. The translation vendor should select the appropriate translators for the job and consistently evaluate their work.

Translation memory: It goes without saying that a good translation vendor uses translation memory (TM) in their workflow. Leveraging the TM can ensure consistency in translation and reduce overall translation costs and turnaround times, provided the source content is also consistent. If inconsistencies are found, the translation vendor should work with the content creators to correct it so the inconsistency isn’t added to the TM. Further, the TM itself should be audited on a regular basis to clean out any inconsistencies that may have crept in over time.

In-country review: An in-country (or local) review of translations is critical for tailoring translated content to the target audience. Language varies by location (would you like a pop/tonic/soda/coke to wash down that sandwich/hoagie/grinder/sub?), and the local review ensures that the translation is appropriate for the target audience. Failure to conduct these reviews can result in misunderstandings between the audience and the content, causing a scramble to correct the issues and a negative perception of your company in that location.

Any one of these links could be a point of failure in your localization chain. By identifying and strengthening that link, you will not only improve the quality of your localized content, but will likely save time and money in the process. Evaluate your localization chain often; strengthening one link may help identify another than also needs attention.

Content strategy amateur hour

July 7, 2015 by

“My team is looking into how we can use <incumbent tool> to handle our new content requirements.”

That’s what I heard from a manager during a recent phone call about a company’s expanding content needs. The tools-focused response made me cringe.

This is not the first time I’ve encountered content developers using a current tool’s capabilities as the benchmark for content requirements. An incumbent-tools-first approach is an easy way out that maintains the status quo.

Periodically assessing how efficiently you’re using tools is sensible, but don’t fool yourself into thinking that checkup is a complete process analysis. A true content strategy assessment looks at how content supports business requirements and then investigates which tools best support those needs. The list of prospective tools should include the incumbent if—and only if—that tool meets the criteria for supporting business goals.

When developing a content strategy, content professionals are anything but professional if they do not step outside the comfort zone of the tools they use every day.

Please don’t be one of those amateurs.

Waterfall content development? You’re doing it wrong.

June 29, 2015 by

Product development, content development, and localization processes are too often viewed as a waterfall process.

This is not at all accurate.

Waterfall: product to content to localization is highly unlikely.

Waterfall. As if.

Product development decisions do feed into content and content into localization, but, in the other direction, localization decisions also drive product development. For example:

  • Every time you add a new locale, you need to make sure that your product can support the local language, regulations, currency, and so on. Regulatory requirements might drive product decisions—the European Union, for example, has strict requirements around personal data protection.
  • In a country with multiple official languages (like Switzerland or Canada), you may need to provide a way to switch a product interface from one language to another.
  • If you want to deliver content as part of the product, you need to make sure that your product has enough storage space available for product content.
  • If you want to deliver web-based content with periodic updates, how do you handle the connection from the product to the content?
  • What if you want to have troubleshooting instructions that use product information directly? How do you integrate the instructions with the product status? How do you do that in 57 different languages?

This leads me to the unified theory for development:

Product, content, and localization maturity are interdependent. A mature process in one area requires alignment with mature processes in other areas.

Instead of waterfall, think of content, localization, and product as sides of a pyramid.


Three-face pyramid with content, product, and localization on the faces.

Content, product, and localization all contribute to the overall development process.

Your development process is a slice across the pyramid that intersects all of the faces.

Three-face pyramid with horizontal slice.

If your processes are equally mature, development works well.

What you want is a horizontal slice—the development process in sync across all of the faces. If the processes are out of alignment and do not have similar levels of maturity, you end up with an unstable platform that is impossible to stand on. Problems on the lower (less mature) side will cause instability everywhere.

Three-face pyramid with angled slice.

Different levels of process maturity make for an unstable development platform.

Here’s are some examples of misaligned processes:

  • Localization needs to deliver languages that the product didn’t account for. Suddenly, you have a need for Thai characters, and no way to embed them in the software.
  • Product is cloud-based software that is updated weekly. Content development process can only provide PDF that is updated every six months.
  • Product ships with all languages enabled, but localization process requires another eight months to provide content in all languages.
  • Content development process is frenetic and unpredictable. Localization costs skyrocket because of lack of style guides, consistent terminology, and formatting templates.

When we develop content and localization strategies, we must assess the maturity of the product development process. The right content strategy may require the organization to make changes in product development and vice versa. Product, content, and localization strategies all need to be aligned at similar levels of maturity.

Put another way: Your content strategy can’t get too far ahead of your product strategy.

Webcast: Risky business: the challenge of content silos

June 25, 2015 by

In this webcast recording, Sarah O’Keefe discusses how content silos make it difficult to deliver a consistent, excellent customer experience. After all the hard work that goes into landing a customer, too many organizations destroy the customer’s initial goodwill with mediocre installation instructions and terrible customer support.

Do you have a unified customer experience? Do you know what your various content creators are producing? Join us for this thought-provoking webcast.


Localization, scalability, and consistency

June 23, 2015 by

When companies need to change the way they’re producing content, localization and scalability can be two of the biggest motivating factors. If your company’s content is not consistent, you may face significant challenges with translating it into new languages or distributing it via new platforms. A content strategy that embraces consistency and emphasizes planning for the future will help your company navigate these changes more smoothly.

(flickr: Beverley Goodwin)

(flickr: Beverley Goodwin)


Localization is usually difficult, time-consuming, and expensive—especially if your company is doing so for the first time. Even if you’re already localizing your content, a major increase in the number of required languages or a demand for new types of languages (such as right-to-left) may suddenly feel like more than your current process can handle. Here are some ways you can make localization easier and offset costs:

  • Prepare your content. Using consistent terminology, avoiding jargon, and practicing cultural awareness when you’re creating your source content can make it more ready for translation.
  • Plan ahead. As your company grows, localization will become more and more of a requirement. If you have target markets in other countries in mind, it never hurts to start researching their localization needs ahead of time.


Companies can grow and scale up their operations in a number of ways. Maybe your company is growing larger, hiring more employees, and developing more products. Maybe you’re getting requests for content distribution through a wider variety of channels (print, PDF, HTML, online help), optimized for desktop and mobile. You might also be expanding into the global market, which means scalability will go hand-in-hand with localization.

Thinking about your company’s long-term goals for growth and planning for the future can help you avoid some of these common roadblocks to scalability:

  • Your content creation process is too slow or too small-scale to keep up with the demands of company growth.
  • Your content creation process can’t handle new localization requirements.
  • Your content is developed in a way that results in limited output types (such as a desktop publishing system that can’t produce output in electronic formats).


When it comes to localization and scalability, inconsistent content can be part of the problem, so making your content more consistent can be part of the solution. Inconsistency makes translation and legacy conversion difficult, introduces accessibility issues, and ultimately hurts your brand. Here are some ways you can make your content more consistent:

  • Have a style guide (and use it). Train your content creators on consistent style and make checking for consistency a major focus of the review process.
  • Replace manual processes with automated ones. If a style guide alone is unreliable, use templates to help enforce it. The more you automate your content development, the less room you have for human error.
  • Consider controlled language software. If inconsistency is a huge pain point for your company, it may be best to invest in technology that can strictly enforce language and style.

Getting your content consistent can be difficult, especially if you’re currently working without a style guide or templates, but the rewards are worthwhile. Consistency can save your company money by allowing you to produce, translate, and publish your content more quickly and efficiently. With consistent content, localization and scalability will seem less like insurmountable obstacles and more like exciting markers of company growth.

To see how much your company could save by creating more consistent content, try our business case calculator.

The content strategy of things

June 15, 2015 by

This post is a recap of the presentation I delivered at Localization World Berlin on June 4, 2015. It describes how and why to adapt a content strategy in support of The Internet of Things. The presentation slides are available on SlideShare.

What is the content strategy of things? To simplify definitions, content strategy is the planning for and governance of the content lifecycle, and the Internet of Things is the connecting of devices and software to provide greater value. To adapt content strategy to the Internet of Things, the content strategy of things can be defined as the planning for and governance of connected content to provide greater value.

The Thinker

Flickr: Brian ⚓ Hillegas

As with any content strategy, proper planning is critical. All parties involved in hardware, software, and content must be involved. A shared understanding of the associated systems and the people using them is required. And since these connected devices, systems, and people could be anywhere, localization and cultural understanding is critical.

When we think of content, minimum viable content for consumption must be accurate, concise, and complete. This means it must exist and be available when needed, that it is factually correct, and that it is appropriate for the audience (in the proper language and format).

However, content that supports the Internet of Things cannot stop there. Since device and systems communication involves fragments of information being passed as needed, the content that supports this communication must also conform to this fragmented model. To engage users and talk between devices and contexts, content must be intelligent.

Intelligent content is structurally and semantically rich, reusable, reconfigurable, and adaptable. Content can stand alone as small snippets of information or be combined into longer blocks of information. And since it is XML-based, it can be transformed into any format required.

There are many models that support intelligent content, but one that stands out is the SNOMED CT model. In this content model, every concept gets a unique ID and contains multiple human-readable descriptions and relationships.

SNOMED is probably the best example that explains how content needs to work in order to support the Internet of Things. Rather than think in terms of independent topics, we need to start thinking in terms of contextual topic families. A family could consist of short and long entries for feature names and descriptions, and could contain many other types of topics depending on the types of information needed. Depending on the device and purpose of the content, only certain topics from that family would be requested and presented.

Topic family example

While we currently lack governance over human-facing content in the Internet of Things, moving to such a model would allow for a nimble transition to a future standard, and would continue to suit more traditional content deliverables.

If you would like to learn more about modeling content in this manner, you can contact us or leave a comment below.

Localization strategy and the customer journey (premium)

June 8, 2015 by

This premium post is a recap of a presentation delivered by Sarah O’Keefe at Localization World Berlin on June 4, 2015. It describes how and why to align localization strategy to the customer journey.

The new buzzword in marketing is the customer journey. What does this mean for localization?

The customer journey describes the evolving relationship between a company and a customer. For instance, a simple customer journey might include the following stages:

  • Prospect: conducts product research
  • Buyer: purchases product
  • Learner: needs help to figure out how to use the product
  • User: uses the product
  • Customer: owns the product, uses it occasionally
  • Upgrader: needs new features or has worn out the product and needs a new one
  • Repeat customer: buys the next version
Funnel with trade show, research, SEO, engagement, white paper, prospects, and emails going in at the bottom. Purchase is the output at the bottom of the funnel.

The marketing funnel ends with a purchase.

The idea of the customer journey is replacing the sales and marketing funnel, in which the end state (the bottom of the funnel) is a purchase.

Instead, the customer journey acknowledges a more complex relationship with the customer.

Stages of customer journey in a circle: research, buyer, learner, user, customer, upgrader

The customer journey continues after buying.

In the traditional marketing funnel, content is critical before the “Buy” decision. After that, content is not important. In a customer journey, all stages are critical and consistency is important.

There is content required at each stage of the customer journey:

  • Research: web site, marcomm, and white papers
  • Buyer: e-commerce and proposals
  • Learner: training
  • User: documentation
  • Customer: knowledge base, support
  • Upgrader: what’s new

Unfortunately, delivering this content with consistency can be quite difficult because it is created in lots of different places in the organization.

Corporate organization chart shows content being developed in different locations: training is under the CIO, proposals are under the COO, and so on.

The organizational chart makes consistent content difficult.

The localization maturity model is helpful here. The original was developed by Common Sense Advisory, but I have created a slight variant:

Instead of reactive, managed, optimized, negligent, and so on, we have anger, denial, bargaining, depression, and acceptance

With apologies to Common Sense Advisory, I have simplified their maturity model

Minimum viable localization is somewhere between level 1 and level 2 (between reactive and repeatable in the true maturity model). In most organizations, the localization maturity is different for different types of content. If you think about your content and map it against the customer journey, it probably looks something like the following:

Marketing content gets a 2; user documentation gets a -3 on the CSA localization maturity model.

Localization maturity varies by content type

Seen from the customer journey point of view, the problems are obvious. The prospect and buyer gets pretty good localized content, the learned gets something acceptable, and the user/customer gets the dregs. The company then attempts to redeem itself as the customer moves into the new buying cycle with better delivery for the upgrader/potential customer. This seems like a dangerous approach. A better strategy is to move all of the content into alignment at the same maturity level.

Consistency is critical. We recommend starting with the following:

  • Consider using a single vendor to make consistency easier. At a minimum, avoid fragmented, siloed localization efforts.
  • Work on voice and tone in source and target languages. Assess how they are different for different kinds of information.
  • Implement consistent terminology.

For some localization service providers (LSP), the need for consistency presents a business opportunity. A customer might choose a single vendor to make consistent content delivery a little easier. For a specialist LSP, this could be a problem. For example, a company that focuses on transcreation of marketing content would not be well-positioned to take on technical training materials. A company that specializes in a particular industry, such as biotechnology, might be in a position to argue for more investment by their customers.

For localization buyers, here are some recommendations:

  • Establish long-term vendor relationships. Commodity buying is not going to get you the quality you need to support a great customer journey.
  • Make sure the translation memory is available, updated, and shared among all your vendors.
  • Consider assigning LSPs by product rather than content type.

Localization strategy needs to change to support a customer journey. Here are some basic tips:

  • Understand your (or your client’s) customer journey
  • Understand localization requirements at each point in the journey
  • Develop a strategy that addresses each requirement
  • Ensure that you have terminology management, translation memory, and other assets in place across the enterprise
  • Different parts of the customer journey need different approaches to voice and tone. Include those in your customer journey planning.
  • Different locales may have different customer journeys. Align your translation priorities accordingly.

The customer journey is only as good as the weakest link in the content and localization chain.


Reducing tedium in content workflows with exceptionally mobile technology

June 2, 2015 by

The content lifecycle can involve many needlessly tedious tasks. Perhaps the most tedious of tasks is review tracking. There are many ways to send content out for review. Some people prefer using a manual process, others prefer automated workflows. Whatever approach you use is fine, provided one critical detail: that the reviewer actually read the material.

To date there is no sure-fire way to ensure that reviewers read the material assigned to them. No matter how many alerts they receive, and no matter how many times you bug them, there is no systematic way to ensure that reviewers read and comment on the material in a timely manner.

But what if there was?

Unless you’ve been living under a rock for the past few years, there is a wonderful technology being adopted for any number of purposes, from photography to package delivery:


Drones are small, highly maneuverable, emissions-free (well, the electric ones are), and they can be piloted automatically using sensors and programmed instructions. They would be the perfect companion to any writer who is desperately chasing after reviews!

drone copter

Flickr: Richard Unten

Imagine the ease of producing a review copy of a document and having a drone fly it over to a reviewer. To ensure that the reviewer doesn’t miss the delivery, you can configure the review system to monitor the reviewer’s workstation. When activity is confirmed, the drone can fly over, sound off an airhorn, release confetti and drop the document off for review (perhaps with a piece of chocolate for an added incentive and an advance “thank you” to the reviewer).

A few days before the review is due, if you haven’t received feedback, the drone can be sent out to gently remind the reviewer of their responsibility. You can use the same routine as you did in the initial drop-off, or you can equip the drone with any number of attachments to provide an extra incentive. (Please consult your employee manual and HR department before enabling air-to-surface projectiles.)

If the review date arrives and you still haven’t received feedback, you can then switch the drone to Bloodhound Mode. The drone will seek out the reviewer and follow them until the review is complete. Depending on the accessories you equip the drone with, it could play an audible alarm, flash lights, and record what the reviewer is doing instead of reading the material. You can even tie the cameras into your company’s intranet so everyone can see first-hand just how busy your reviewer is!

The applications aren’t only limited to reviews, though. Authors who are approaching their own deadlines can be “motivated” by a friendly visit from the drone squadron, as could subject matter experts who can’t seem to find the time to share critical project information. Add an extra battery or fuel tank and you could even send them out to check on your localizers!

Employing drones in every step of the content lifecycle will achieve results and add excitement to any work environment! You’re certain to see an immediate return on investment as well. As your traditional “office drones” are freed up to perform more meaningful work while the flying drones handle the chasing and hounding, productivity will soar as high as morale will carry it! So choose your features wisely and RELEASE THE DRONES!!!