Scriptorium Publishing

content strategy consulting

Design versus automation: a strategic approach to content

August 10, 2015 by

Design and automation are often positioned as mutually exclusive–you have to choose one or the other. But in fact, it’s possible to deliver content in an automated workflow that uses a stellar design. To succeed, you need a designer who can work with styles, templates, and other building blocks instead of ad hoc formatting.

More content across more devices requires scalability–and that means more automation. A strategic approach to content needs to incorporate both design and automation as constraints and find the right balance between the two.

Prelude

First, a few definitions.

Design–specifically graphic design–is the process of deciding how information is presented to the person who needs it. The design effort may include text, graphics, sound, video, tactile feedback, and more, along with the interaction among the various types of information delivery. In addition to the content itself, design also includes navigational elements, such as page numbers, headers and footers, breadcrumbs, and audio or video “bumpers” (to indicate the start or end of a segment). Sometimes, the designer knows the final delivery device, such a kiosk in a train station or a huge video board in a sports stadium. In other cases, the delivery is controlled by the end user–their phone, desktop browser, or screen reader.

Automation is a workflow in which information is translated from its raw markup to a final packaged presentation without human intervention.

Theme

Design and automation are not mutually exclusive.

designvautomation_line

Instead, think of design and automation as different facets of your content. Each quadrant of the design-automation relationship results in different types of documents. High design and low automation is where you find coffee table books. High automation and low design encompasses invoices, bad WordPress sites, and 30 percent of the world’s data sheets. Low design/low automation is just crap–web sites hand-coded by people with no skills, anything written in Comic Sans, and the other 70 percent of data sheets. (Seriously, where did people get the idea that using InDesign without any sort of styles was appropriate for a collection of technical documents? But I digress…)

The interesting quadrant is the last one: high design and high automation. In this area, you find larger web sites, most fiction books, and, increasingly, marketing content (moving out of lovingly handcrafted as automation increases) and technical content (moving out of “ugly templates” and up the design scale).

Design/automation on X/Y coordinates. Automation is the X axis; design is the Y axis.

Design and automation and different facets of content creation.

The world of structured content inhabits a narrow slice on the extreme right.

Automation on the X axis; design on the Y axis. Structured content is a band in the high-automation area.

Structured content goes with high automation.

Design gets a similar swath of the top.

Automation on the X axis; design on the Y axis. Design-centered content is a band in the high-design area.

Design-centered content at the top of the design region.

When you combine a requirement for high design with a requirement for high automation, you get The Region of Doom.

Same grid at before. The region of doom is the top left corner, where you have extreme design and extreme automation requirements.

You can accommodate 90% design and 100% automation or 90% automation and 100% design, but if you are unwilling to compromise on either axis, expect to spend a lot of money.

A better strategy is to focus on the 90% area. By eliminating 5–10% of the most challenging design requirements, or by allowing for a small amount of post-processing after automated production, you can get an excellent result at a much lower cost that what the Region of Doom requires.

The intersection of design and automation bars in the upper right is the best value.

Small compromises in design and/or automation result in big cost savings.

Exposition

When we discuss design versus automation, we are really arguing about when to implement a particular design. An automated workflow requires a designer to plan the look and feel of the document and provide templates for the documents. The publishing process is then a matter of applying the predefined design to new content.

The traditional design process ingests content and then people apply design elements to it manually.

In other words, automation requires design first, and this approach disrupts the traditional approach to design. Like any disruptive innovation, this new approach is inferior at first to the “old way” (hand-crafting design). As the technology improves, it takes over more and more use cases.

Disruptive technology first takes over the low end of the market, and then gradually moves up to more demanding users.

Evolution of disruptive technology over time, public domain image found at Wikimedia

Travis Gertz writes an impassioned defense of editorial design in Design Machines: How to survive the digital apocalypse:

Editorial designers know that the secret isn’t content first or content last… it’s content and design at the same time.

[…] When we design with content the way we should, design augments the message of the content.

[…] None of these concepts would exist if designed by a content-first or content-last approach. It’s not enough. This level of conceptual interpretation requires a deep understanding of and connection to the content. A level we best achieve when we work with our editors and content creators as we design. This requirement doesn’t just apply to text. Notice how every single photo and illustration intertwines with the writing. There are no unmodified stock photos and no generic shots that could be casually slipped into other stories. Every element has a purpose and a place. A destiny in the piece it sits inside of.

He provides wonderful examples of visuals entwined with content, mostly from magazine covers. And here is the problem:

  • As Gertz acknowledges earlier in the article, for many small businesses, basic templates and easy web publishing are a step up from what they are otherwise able to do. Their choice is between a hand-coded, ugly web page (or no web presence at all), and a somewhat generic design via SquareSpace or a somewhat customized WordPress site. Magazine-level design is not an option. In other words, automation gives small business the option of moving out of the dreaded Meh quadrant.
  • What is the pinnacle of good design? Is it a design in which graphics and text form a seamless whole that is better than the individual components? Many designers forget that not everyone can handle all the components. A fun audio overlay is lost on a person who is hard of hearing. Without proper alternate text, a complex infographic or chart is not be usable by someone who relies on a screen reader.
  • The vast majority of content does not need or deserve the high-design treatment.
  • An advantage of visual monoculture is that readers know what to expect and where.
  • All of these examples are for relatively low volumes of content. I don’t think these approaches scale.

Coda

What do you think? Scriptorium builds systems that automate as much as possible, and then use additional resources as necessary for the final fit and finish. Only some limited subset of content is worth this investment. I know that I have a bias toward efficient content production so that companies can focus on better information across more languages.

For more on this topic, come see my session at Big Design Dallas in mid-September.

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 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.

 

Renovate or rebuild? Construction as a content strategy model

May 26, 2015 by

Does your house have good bones? Ugly paint, terrible carpet, and dated appliances are all fixable. But if a room is too small, a door is in the wrong place, or the rooms don’t match your requirements (need a downstairs master bedroom?), then you have a serious problem.

Content can also have good bones. Or not.

The content audit is like a home inspection. What information do you have already? Is it the right information? How is it put together? What sort of issues are there in the content? Do you need to update your kitchen, er, content?

Meeting building codes

If you don’t meet building codes, you are going to have a serious problem with your city building inspector when you try to sell your house.

Your content strategy needs to take into account the content building codes, which may include the following:

  • Requirements for accessibility
  • Regulatory requirements
  • Reader expectations

Build these into your upfront construction plan, or face huge expenses later when you fail your inspection.

The foundation

You need a strong foundation for your content. Unfortunately, that can be difficult because foundation requirements vary by industry.

Back to our house analogy: Here in the Piedmont region of North Carolina, we have clay soil. It’s fabulous for making bricks and growing tobacco, and very little else. With clay soil, you generally build either slab or pier-and-beam foundations. Very few houses have basements, unless they are built on the side of a hill. Unlike California, we don’t worry too much about earthquake-proof foundations. In coastal areas, we worry about hurricane tie-downs and possibly flooding.

With content foundations, you have a couple of different problems: Only a few lucky industries have bedrock content architecture that you can rely on. Everywhere else, you can count on seismic shifts in your requirements every few years. There will be new content platform that you must support, new regulatory requirements, new languages, changes in available skill sets, and new requirements for integration across the organization. (You thought you were building a house for your family, but now your quirky cousin from Maine is living with you. And she brought two tons of books with her.)

Overbuilding

Kitchen with missing appliances. Remodeling in progress.

Kitchen remodeling // flickr: sellis

One of the biggest home renovation risks is overbuilding. A little granite here, an appliance upgrade there, a few dozen custom cabinets with inlaid wood, an inability to say no to those organic bamboo floors, and suddenly your kitchen looks like something out of Food & Wine. It’s fabulous, but you are the Queen of Takeout. Why do you have a built-in wok and a triple oven?

Some organizations need industrial-strength content. Others just need to reface the cabinets or maybe clean the range for once. Before you start your content strategy work, understand your neighborhood. Will you get your investment in content back? What is your ROI? Will additional investment give you better results?

Scorched earth: when is razing appropriate?

In some housing markets, complete tear-downs are common. The house is sold, and then the new owners raze the building and build something brand-new on the same site. Tear-downs usually occur in desirable areas where land is very expensive—the land is relatively valuable compared to the building.

Perhaps you have a great web site URL and terrible content that populates it? Or perhaps your content is so dingy that it would be cheaper to start over. If you need to redesign all aspects of content production from who creates it to its delivery mechanism to the information architecture, it may be less expensive to start over than to try to glue your new design onto avocado-colored 70s content.

Cosmetic fixes are cheap

All renovations are deeply painful for the content owners and the inhabitants of the house. Basic fixes, like new paint or a new look-and-feel for your output, are faster, cheaper, and easier than moving walls or breaking down content silos.

But is a cosmetic fix going to fix your problem?

A word about rental property

If you live in rental property, your redesign options are limited. You can paint and move furniture around, but you probably can’t do more. If you are publishing content on a host platform, like Facebook, Medium, or Pinterest, you are constrained by what your landlord allows.

DITA training call for participation

May 1, 2015 by

One of the major challenges in implementing DITA projects is training. Although we (and others) offer fabulous live, instructor-led training, there is also a need for asynchronous learning–where can a student go to learn DITA independently? To address this need, Scriptorium is starting an open-source effort to develop training content for DITA.

We have chosen GitHub for the repository, and you can find the project here:

https://github.com/okeefescriptorium/ditatraining

The content is licensed under Apache (same as the OT) with the possible exception of a few graphics that we might get from Flickr under Creative Commons.

The materials include short videos that help explain key points.

We are also adding external links to information that people have already published.

If you are a DITA user, and especially a DITA expert, we need your help. Please consider contributing content to the repository. We have providing a starting point with basic DITA content, but there is an enormous amount that needs to be done.

To contribute, you’ll need to know a few things about how to use GitHub. If you are already involved in other GitHub projects, you can fork the ditatraining repository. If that sounds vaguely obscene, you might want to read GibHub for Beginners.

There is a very basic style guide provided as a DITA topic at the root level of the repository. Here are some highlights:

  • Most content uses the learning specialization.
  • Include author names in the prolog, along with a creation or modification date.
  • Each learning module has instructional content and assessments.
  • We have provided a recommended file structure and topic breakdown.

Our next step will be to publish the learning content into an interactive web site. More on this later.

Will you help us build a DITA training resource for the community? Please participate on GitHub, or contact us to volunteer your help.

Uber, disruption, and content strategy

March 30, 2015 by

I used Uber and lived to tell the tale. And I found a lesson for content strategy in my rides to and from the airport in San Francisco.

Uber competes with taxi and car services. It is controversial and possibly disruptive.

From the customer’s point of view, Uber is an incredible improvement. It fixes all the bad things about the traditional taxi experiences—you get cashless transactions, a map on which you can watch your ride approach, and lower fares than taxis (sometimes). No tipping. Near-instant response.

But look a little deeper, and I’m troubled by the business model that seems unfair to taxi drivers, who have been thoroughly vetted and who paid a lot of money for their taxi licenses. Uber undercuts this model by providing the technology layer that connects drivers to riders, and arguing that they are not in fact a transportation company, only a match-maker for ride-sharing. The German government disagrees, and has banned some Uber services, as has the city of Portland, Oregon and several other jurisdictions around the world. Uber has also engaged in some…questionable…business strategies.

But my misgivings about using them were outweighed by the convenience and, critically, the strong recommendations from Val Swisher and Scott Abel, both of whom are Bay Area locals. After using Uber and emerging unscathed, I offer some lessons for content strategists:

  • The customer wants a good experience. They don’t really care about how you achieve the good experience. Your organizational problems are of no interest to the customer, only your interaction with the customer. A few companies have made their ethics a key reason to buy (Patagonia and Ben & Jerry’s come to mind), but without an explicit story, customers will not make this connection on your behalf. (Possible content marketing strategy for taxi companies: Tell the story of their cabbies—the plucky immigrant who is living the American dream, the New York native who loves working on cars and knows all the back roads, and so on.)
  • Your regulatory problems are of little interest to me, er, them. (Possible exception: life-and-death content, such as medical information or aircraft maintenance information.) Uber has aggressively positioned taxi regulations as outdated and inconvenient. The taxi companies need to tell the story of why the regulations are necessary and good, such as launching a sustained campaign around Uber’s infamous surge pricing policy.
  • Banning your unauthorized competitor is probably not going to work. (It doesn’t work with Uber; it’s definitely not going to work with information.) So figure out how to accommodate illicit content as part of your strategy. Or improve your customer experience so that people don’t go looking for a (possibly sketchy) alternative. (Unauthorized translations by resellers come to mind. They usually happen when the content owner fails to make the content available in the needed languages.)

Uber is a cautionary tale for anyone who makes their living in a closed market.

After finishing this article on Friday afternoon (March 28) and scheduling it for publication on Monday morning, I received this email late Friday night:

They are your drivers, and we want to celebrate them. Meet the people behind the wheel who make it all possible. (Image of smiling driver.)

Well played, Uber. Well played.

Buyer’s guide to CCMS evaluation and selection (premium)

March 2, 2015 by

“What CCMS should we buy?”

It’s a common question with no easy answer. This article provides a roadmap for CCMS evaluation and selection.

First, a few definitions. A CCMS (component content management system) is different from a CMS (content management system). You need a CCMS to manage chunks of information, such as reusable warnings, topics, or other small bits of information that are then assembled into larger documents. A CMS is for managing the results, like white papers, user manuals, and other documents.

1. Why do you need a CCMS?

assortment of yarns in store

Why do you need a CCMS? // flickr: lollyknit

The very first step in CCMS evaluation is to determine why you need a CCMS. (Sorry, this sounds like a Fight Club reference.) What business problem are you trying to solve? I am amazed at the number of people who think they need a CCMS but cannot articulate why. Some common reasons for CCMS implementation are increases in:

  • Volume of content
  • Translation requirements
  • Velocity of content
  • Versioning

Before you do anything, understand the scope of your problem and whether a CCMS can solve it. What is broken? Is it more broken than last year? Why? Some common examples of problems that a CCMS will not solve are:

  • Content is inaccurate.
  • Writers lack necessary technical expertise.
  • Departments are siloed because of a lack of mutual professional respect.
  • Content creators refuse to follow style guides because their content is special.
  • In short, all of the People Things™.

If you have issues with People Things, you need to address those in addition to (and preferably before) any CCMS initiatives.

2. What is your ROI?

CCMS implementation is expensive. The cost of CCMS software varies, but implementation is expensive no matter what. Assuming you have a problem that a CCMS will address, your next step is to calculate your approximate return on investment. You’re looking for a rough order of magnitude here, and much of this calculation is driven by your scale. If, for example, you have 50 full-time content creators, and you assume a loaded cost of $100,000 per person per year, then a 10 percent improvement in efficiency is equal to around $500,000 in yearly savings.

By contrast, if your annual translation budget is $50,000, you probably won’t find ROI justification in cutting translation costs.

You can build ROI based on:

  • Cost avoidance
  • Increased revenue
  • Time

Cost avoidance is an efficiency argument: “If we buy X, we can do task Y with less effort.”

Increased revenue is an investment argument: “If we buy X, we will get more income from Y.”

Time is usually a time-to-market argument: “If we buy X, we can deliver Y in two months instead of six months.”

Our XML business case calculator lets you estimate your potential ROI from a transition from desktop publishing to XML.

Once you have some sort of idea of the cost improvement (the “return” part of ROI), you can move on to figure out the other side of the equation–how much do you need to invest? Your initial cost estimates will tell you what class of CCMS you should be looking at. For general guidance, refer to our XML workflow costs article.

3. There is no bad CCMS. Only bad fits for you.

The trick to buying the right CCMS is to find the one that meets your requirements. Every system on the market has strengths and weaknesses. There is no single Best CCMS, nor is there a Bad CCMS. What we have is systems that are better in some scenarios than others. Therefore, you need to figure out the following:

  • What are your priorities?
  • Which system best matches your priorities?

Figuring out your own requirements is your job. Once you have some vague idea of what you need and have done preliminary research, consider issuing a formal RFI (request for information) to get better vendor information.

At this point, you should not be issuing an RFP (request for proposal). You don’t know exactly what you want to ask for yet.

4. What features do you need?

Knitting markers in various shapes

Pay attention to features // flickr: trilliumdesign

“What features do you need in a CCMS?”

“Version control.”

Well, duh. Let’s ask a better question: “What features do you need beyond the basics?” Answers in the past few years from different clients have included items such as:

  • “We have no IT support, so the system needs to be SaaS  (software-as-a-service).”
  • “The system must not be SaaS.”
  • “The system must integrate with [SAP | web CMS | others].”
  • “The system must generate output via [this protocol] to [this format].”
  • “The interface must be available in [this language].”
  • “The system must cost less than [this amount].”
  • “The system must align with the branching techniques we use in [this software development tool].”
  • “The system must be installed and running by [some very soon date].”
  • “The system must support [this content model].”

You want to thoroughly understand your exact requirements and constraints so that you can narrow down your choices quickly. Don’t make a list of boring stuff that every CCMS does. It’s a waste of everyone’s time, especially yours.

Instead, do the following:

  • Identify your most unique requirements (regulatory? system architecture? content volume? languages?)
  • Write up detailed use cases for your most critical requirements and use those to evaluate the systems

Your use case scenarios will help you evaluate the candidates and figure out whether they really meet your requirements.

5. Is extensibility important?

How will your CCMS interact with other systems? Which other systems do you need to interact with? If extensibility is important, focus on the systems that provide a good starting point for this type of integration.

6. What is your exit strategy?

Start planning your exit strategy on the way in. If you ever decide you want to take your content and shift it to another system, will you be able to do so? What is your exit strategy?

7. Vendor relationship

Can you communicate successfully with the CCMS vendor? If not, the implementation and integration process is going to be extremely painful.

Don’t play games with your vendors. The CCMS world is extremely small. People move from one software vendor to another constantly. As a result, there is an excellent industry grapevine. Bad behavior, whether by CCMS vendors, by consultants, or by potential CCMS buyers, is not an option–word gets around quickly.

Not too long ago, I asked a colleague about working with a particular prospect, who seemed a bit….difficult. His response? “Run. Run fast. Then hide.”

Test your vendor relationship with a low-budget, low-commitment pilot project.

Additional resources

This brief overview only scratches the surface of what you need to consider. More resources:

Conditional content in DITA (premium)

February 9, 2015 by

This post provides an overview of techniques you can use to handle conditional content in DITA. The need for complex conditions is a common reason organizations choose DITA as their content model. As conditional requirements get more complex, the basic Show/Hide functionality offered in many desktop publishing tools is no longer sufficient.

Conditional processing is especially interesting–or maybe problematic—when you combine it with reuse requirements. You identify a piece of content that could be reused except for one small bit that needs to be different in the two reuse scenarios.

The first step in establishing a strategy for conditional content is to clarify your requirements and ensure that you understand what you are trying to accomplish.

Classes of text variants

DITA offers two basic types of variants:

  • Variables (implemented through DITA keys): a short snippet, like a product name, that often changes.
  • Conditional information: an element or group of elements that needs to be included or excluded selectively. Conditional information can occur at the topic, block, or inline level. Graphics and tables can also be conditionalized.

In DITA, your conditional assignments need to correspond to an element. In unstructured desktop publishing tools, it’s possible to assign conditions to an arbitrary chunk of content. This is not the case in DITA because you need to attach the conditional labeling to an element. (In theory, it’s possible to use processing instructions to mimic the arbitrary labeling, but just…don’t.)

Variables

Here’s what a simple variable looks like. First, you define the variable as a key (in this case, clientname) in the map file.

<map>
    <title>DITA Topic Map</title>
    <keydef keys=“clientname”>
       
<topicmeta>
            <keywords>
                <keyword>My First Client</keyword>
           
</keywords>
        </topicmeta>
    </keydef>
    <topicref href=“sample.dita”/>
</map>

Inside the topics, you reference the key:

<p>When we deliver this information to <keyword keyref=“clientname”/>

You use a placeholder for the keyword in your text, and you use the map file to define the value of the placeholder. Therefore, you can use a single topic with a keyref along with multiple map files. The result will be different output for the key reference for each of the maps. (DITA 1.3 adds scoped keys, which allow you to change the key’s value inside a single map file.)

Conditions

In DITA, you use attributes to identify conditional content:

<p>This paragraph is for everyone.</p>
<p
audience=“advanced”>This paragraph is only for advanced users.</p>

<note><p>
      It’s possible to do conditional content at the phrase level<ph platform=“badidea”>, but it’s a really terrible idea</ph>.
</p></note>

If you have more complex combinations, you use more than one attribute:

 <p audience=“expert”

      platform=“windows”

      product=“X”>content goes here</p>
<p audience=“expert” 

           platform=“windows mac”

           product=“X Y Z”>other content here</p>

Do not use conditions below the sentence—preferably paragraph—level.

Why not, you ask?

<p>The colo<ph xml:lang=“en-uk”>u</ph>r of money is a very speciali<ph xml:lang=“en-uk”>s</ph><ph xml:lang=“en-uk”>z</ph>ed topic.</p>

Two reasons:

  1. Your translator will hate it.
  2. You will go insane.

Specifying conditional output

Once you have assigned your attribute values, you use a ditaval file to specify what to include and exclude when you generate output through the DITA Open Toolkit. Here is a simple example:

<val>
<prop action=“include” att=“audience” val=“expert”/>
<prop action=“include” att=“product” val=“X”/>
</val>

Markup is the small(er) challenge

You assign attributes to an element to make it conditional. You can assign conditions, therefore, to anything that has an element, all the way down to phrases, words, or even letters (but again, don’t go below sentences). DITA gives you three attributes out of the box (audience, product, platform) for conditional processing. If you need more or different attributes, you’ll need to specialize.

Establishing a reasonable taxonomy and information architecture presents a much more difficult challenge that the actual assignment of conditional markup. You have to figure out which attributes to create, what values they should have available, and how you might combine the attributes to generate the variants you need.

Consider the case of information that is applicable only to a specific region, like California:

<warning audience=“ca”>
     <p> This product contains chemicals known to the State of California to cause cancer and birth defects or other reproductive harm.</p>
   </warning>

This works, provided that your regions are limited to the fifty U.S. states. If you needed to flag information for Canada, that “ca” designator would suddenly become problematic. Perhaps you’d try specifying the country in addition to the state:

<warning audience=“usa-ca”>…California content… </warning>

<warning audience=“ca”>…Canada content…</warning>

As long as you planned for California and Canada, everything will be OK. The problem occurs when you start with a list of states and an assumption that you’ll never need non-US regions, and then suddenly you do.

Conditions and reuse

The combination of conditional variants and reuse is especially problematic. One interesting solution is to use a conref push. A conref push allows you to insert (or “push”) information into a topic.

We use this technique in some of our software assessments. We have a general overview of a particular piece of software with information our clients need, like cost, licensing terms, supported platforms, and so on. But we also need to include our overall recommendation for or against that software. This final bit of information is different for each customer.

To accommodate this, we set up the location where the information is needed with an ID. In our case, this is the last paragraph in the assessment of XYZ tool:

<p id=“xyz”>We recommend XYZ if ABC is a critical requirement.</p>

We then create another topic, referenced in the parent map file as a resource, that provides the information to be inserted:

<p conref=“file.dita#id/xyz” conaction=“mark”/>
      <p conaction=“pushafter”>Using XYZ would eliminate the manual formatting that currently takes up so much production time at ClientA.</p>

For another client, we have a different map file and a different piece of content to be inserted:

<p conref=“file.dita#id/xyz” conaction=“mark”/>
      <p conaction=“pushafter”>XYZ does not support right-to-left languages (such as Arabic), which ClientB needs.
</p>

 

What are your experiences with DITA conditional content?

The talent deficit in content strategy

February 2, 2015 by

Content strategy is taking hold across numerous organizations. Bad content is riskier and riskier because of the transparency and accountability in today’s social media–driven world.

But now, we have a new problem: a talent deficit in content strategy.

Our industry has talented people; it’s just that the demand for content strategists exceeds the available supply. Furthermore, we have an even bigger problem in writing, editing, and production. Enterprise content strategy very often means the introduction of professional-grade tools and workflows (such as XML, CMS, and rigorous terminology and style guides), but many content creators are unprepared for this new environment.

Technical deficit

On the technical side, writers need new skills, such as structured authoring, XML, DITA, and CMS usage. Editors—who move into information architecture roles—must understand how to apply metadata and how to build an effective set of metadata for specific requirements. Deep knowledge of reuse types and applying them is critical. An understanding of localization best practices is helpful for any global organization.

The most technical roles, XSLT stylesheet developers and CMS administrators, must be filled by individuals with a hybrid of IT and publishing skill sets.

Business analysis deficit

Organizations need to first understand their business goals and then use the identified goals to decide on an appropriate content strategy. Here, we face another major skill gap. Although lots of people understand that XML is useful, and some can spell out how XML might be useful, the ability to connect “useful things XML can do” to “what the business needs” is rare. Most publishing people love books. The business component is only of incidental interest.

This presents a problem (or maybe an opportunity) for content strategy consultants.

Why is this a problem

It’s a good time to be a content strategist, a writer with the right technical skills, a stylesheet developer, or a CMS administrator. From your point of view, there are tons of job opportunities, which likely means higher salaries.

When we look at the overall industry, though, we have a problem. Several of our clients have open positions that they are struggling to fill. They are having an especially difficult time finding information architects for DITA. If this continues, the benefits of a very challenging toolset (like DITA) may be outweighed by the lack of available staff. From an executive’s point of view, there are a lot of negatives: more skilled individuals command higher salaries and are hard to find.

Closing the gap

Mind the gap warning next to railroad tracks.

Be aware of the talent gap // flickr: cgpgrey

We won’t close the talent gap any time soon, but here are some suggestions for management:

  • Identify high-potential employees and support them in learning what they need.
  • Recognize that the best employers will get the best talent. If you are not a preferred employer, you may have a long road ahead.
  • Turnover is expensive. Do what you need to do to avoid it.

What’s needed is some really excellent training to start expanding the pipeline of qualified people.

Scriptorium job placement policy

Given the discussion about hiring and recruiting, it seems wise to include a note about our job placement policy.

As consultants, we have unique access to staff across a variety of companies. The tight market is leading to a lot of inquiries about job opportunities. To avoid conflicts of interest, we have a few simple rules:

  1. We do not poach staff from customers.
  2. We do not recruit staff from one customer to another customer.
  3. As long as there is no conflict with these first two items, we provide informal matchmaking assistance to our customers looking for candidates and to individuals seeking new positions. We do not charge for these services.

Are you facing a talent deficit? What’s your plan to address it?

Speaking of talent issues, I give you this gratuitous video: