Scriptorium Publishing

content strategy for technical communication

Beware the monster of change management: THE MAGNIFIER

April 15, 2014 by

For his 1959 horror movie The Tingler, director/producer William Castle had movie theater seats rigged with buzzers to scare moviegoers during a scene when the Tingler creature is loose in a theater. Patrons in those seats probably didn’t enjoy the jolt—or making a spectacle of themselves because of the Tingler’s “attack.”

If you’re managing the implementation of new processes and tools as part of your job, you’re in a hot seat of your very own—and you need to be on the lookout for another horrifying monster: THE MAGNIFIER.

Poster for The Tingler showing a chair and the words, Do you have the guts to sit in this chair?

Poster for The Tingler (Columbia Pictures)

When you’re determining how changes will support corporate goals and calculating the potential return on investment (ROI) for process improvements, it’s easy to get caught up in the excitement generated by the positive things that new processes and tools will bring.

But don’t be lulled into a false sense of security by all the goodness. Lurking in the darkness is the Magnifier, and it will pounce on you if you let your guard down.

So, what is the Magnifier? It’s a phenomenon I’ve witnessed again and again on process implementations: the very act of process change can magnify existing personnel problems in an organization.

For example, if employees do not have a significant understanding of the company’s products and goals, they may create a lot of busy work to mask their lack of domain knowledge. When it comes time to update processes, “busy worker bees” want the details of their unimportant work codified as part of the new processes to make themselves relevant and indispensable (at least in their own minds) in the new workflow. These employees are less interested in the company’s goals than saving their own skins, and that trait becomes even more evident in times of change.

Employees with control issues are highly inflexible and want everything done their way. During process change, they will take a “my way or the highway” approach. For example, if they are dead set on a particular tool set, they will sandbag the tool selection process by exaggerating the feature set of their favored tool and by overemphasizing “problems” with other tool solutions.

Before you think I’m wallowing in unproductive negativity here, please understand I have witnessed the preceding poor behavior on multiple consulting projects (and I’m not even close to cataloging all the bad stuff I’ve seen). As the manager of a process change project, you must be prepared to fight the Magnifier. Effective weapons against it include:

  • Outlining clear business goals for process change. If a proposed tool or process does not support the company’s end goals, it should not be part of the solution.
  • Establishing clear communication among all parties. Start the communication channels up early as possible, and involve everyone, even those who are indirectly affected by the process changes. The company’s business goals should be front and center as part of all change-related conversations. As the project manager, you need to differentiate between legitimate concerns and outright recalcitrance during conversations. Pushback from others can help you identify weaknesses in the proposed workflow that you had not considered.
  • Hiring a consultant, even just part-time. A consultant has seen the Magnifier do its evil thing on other projects and can therefore help you locate and dispose of it early—before it does too much damage. Because consultants come from outside the company, many employees give what they say more credence, even if the consultants end up repeating the very things you’ve been saying all along. A consultant can also act as the “bad cop” in unpleasant situations, particularly ones involving personnel changes (detailed in the next bullet).
  • Realizing that successful change management may depend on personnel changes. Implementing new tools and processes is not going to magically transform poor employees into model workers. In fact, bad employees will have a negative impact on process change. If an employee’s recalcitrance is having significantly detrimental effects, consider reassigning them to another project (for example, maintaining the legacy system), placing them on a performance plan, or even terminating their employment. You must weigh the employee’s value to the company against the drag he or she is creating on the project.

Have you fought off the Magnifier in past projects? Please detail your battle scars in the comments below.

 

Making the most of your conversion to XML, part 2

April 2, 2014 by

You’ve made the transition to an XML workflow for publishing your technical content, converted all of your legacy content, and started authoring in the new system, as discussed in part 1 of this post. Although you now have a much better outlook on sustainability, you’re still facing a problem: your content creators are having trouble with the idea of separating content from formatting.

If you’ve spent years in a print-based workflow, this mindset can be understandably difficult to change. As your content creators work within the new system, new habits will gradually begin to take over the old ones. In the meantime, you can help jump-start their new perspective by showing them how the benefits of an XML workflow outweigh the ability to control every aspect of formatting and page design.

Content that is created and formatted separately will be:

Learn to embrace content creation for multiple outputs. flickr: adactio

Embrace your new publishing possibilities.
flickr: adactio

  • Easier to update. When your content creators don’t have to worry about how things fit on a printed page, they can focus all their attention on the content itself. Since no formatting or design expertise is required to create XML documents, SMEs and other contributors who may not have been qualified to edit the files in a print-based environment can now update the files directly.
  • More consistent. Special, one-off formatting choices that may have made the content less consistent are no longer an issue in XML. When tables, images, and paragraphs are structured the same way every time they’re used, the content will be much better organized, and ultimately easier for the user to consume.
  • More versatile. Content from a single XML source can be transformed into numerous output types—print, PDF, HTML, EPUB—giving the target audience more control over how they want to consume it. Documentation created for print gives the reader a much more limited set of options.
  • More accessible. Content stored in XML is more easily searchable than print documents or print-based outputs such as PDF. Digital outputs from XML (such as HTML) can also be made more accessible by giving the user the option to adjust fonts, sizes, and colors or pass it through a screen reader.
  • More sustainable. Since anyone with or without page design skills can update the content, your content creation team can grow and change over time as needed. It will also be easier for your business to adapt to the development of new products, the introduction of new requirements (such as adding languages to your localization workflow), or overall company growth if your content is in XML. A print-based system will not be as sustainable as XML in an increasingly digital world.

When page design has always been part of your content creators’ process, it won’t be easy for them to break away from that pattern, and it will take time. But with encouragement—and evidence showing how separating content from formatting improves both the user experience and your publishing workflow—they may be a little quicker to embrace the change.

Three cost-saving tips for localizing images

March 24, 2014 by

Translating your content can be an expensive and time-consuming process. While there are many cost-saving practices you can employ, perhaps the easiest and most cost-effective practice involves how you manage your images.

Simplify your image localization process

Avoid unnecessary twists, turns, and delays when localizing your images. (image source: Flickr, StockMonkeys.com)

Regardless of whether you are working with structured or unstructured content, following these three simple tips can save you time and money when localizing images.

Tip 1: Avoid callouts

This is where localization can get expensive. You want to avoid anything that will add time and cost to the process. That said, the best solution is to not use callouts at all, just the unadorned image.

If you must use callouts, only use numbers in the image. Below the image, use a table or list to describe each numbered item. This will keep the image clean, you won’t have to worry about text expansion issues crowding the image, and it will significantly reduce the amount of time it takes to produce a translated image.

If you absolutely must add text within the image, make sure you save the raw source image file (.psd from Photoshop, .ai from Illustrator, etc.) with editable layers intact. This way the translator can easily add the translated text into the source image file, modify its placement as needed, and then save it in a usable format for publishing.

Tip 2: Always link, never embed

When inserting images, insert them as links only. Do not embed them into the content. When you embed the image, you need to manually replace every instance of every graphic. This can be incredibly time consuming if you are publishing several language versions.

When you link the graphic, you are merely inserting a placeholder in the content, and the image resides outside. You are then able to replace the linked image outside of the content once, regardless of where it’s used.

Tip 3: Smart storage

Ideally, you should use a separate images folder for each language translation. This way the relative path from the reference to the images is simple. Place all of your images in that folder and link to them.

Note: If you’re already using a component content management system (CCMS), you can manage your localized images via system features and/or metadata.

When you localize your images, use the exact same filenames for the translated images as you have for the source images. You should have the same number of images using the same filenames in each language folder.

When it comes time to publish your localized content, you can then either overwrite the working images folder contents with the translated images (have a second storage folder for your source images!), or modify the relative paths in the references to the localized images folder. Those translated images will be used without objection, since they are the exact same filenames in the exact same location as when you linked to them. From the content’s point of view, nothing has changed.

Summary

While there are certainly many robust technological ways of managing image translation, it’s always a best practice to start with the basics. These three simple tips will help in your translation efforts regardless of the amount of content you have.

Tools, the content strategy killers

March 17, 2014 by

Quick! What’s the first thing you think about when you want to change the way you produce and distribute content?

If your answer is “tools,” you’re in good company.

First considering the technical aspects of a project is a common and understandable reaction. However, focusing too much on the technology can be the very thing that kills your content strategy.

Image of Jack killing the giant

Jack killing the giant (from The Chronicle of the Valiant Feats of Jack the Giant Killer, 1845)

Soft—or non-technical skills—are essential to evaluate when you’re hiring new staff. By extension, the non-technical aspects of new processes require your attention, too.

You can implement a rigorous tool selection process and spend a lot of time vetting tools, but those investments are useless if you don’t communicate the value of process change. Getting buy-in from all affected parties means you need to offer tailored messages to the different groups. For example:

  • Executives: increased revenue because of shorter times to market.
  • Middle management: cost reduction through more efficient workflows.
  • Content creators: eliminating tiresome manual chores and learning new skills for career longevity.

Your well-selected tool will make it easier to justify process changes to all parties, but it is not going to introduce itself to the different stakeholders, explain its value to them, or train users.

That’s why your content strategy team’s soft skills—particularly in communication—are as important as the tool itself.

 

Making the most of your conversion to XML, part 1

March 11, 2014 by

Your publishing workflow has been the same for years, but new technology, different customer requirements, and company growth are making you realize you might need a change. Your print-based processes won’t always be sustainable, and XML is looking like a possibility for the future. There’s just one problem: you have thousands of pages of legacy content that you’ll need to convert, and it’s not exactly XML-friendly.

flickr_addendentry

Your print workflow won’t sustain you forever.
flickr: addendentry

Here are some simple changes you can start making to your content now to help a future conversion go more smoothly:

  • Create a style guide. The more consistent your content is, the easier it will be to convert to XML. So if you’re not already using a style guide for your documentation, develop one. Decide on the ways your tables, images, lists, headings, and other kinds of text will be structured and define the conventions for how they will be used. Start applying your style guide to all your active documents, and, if possible, update your older documents to adhere to its standards.
  • Tag your content correctly. The paragraph formats you apply will be the basis for how your content gets tagged as it is converted. Therefore, it is important to use these formats as intended—for example, your level-4 heading tag may be the same font and size as your figure caption tag, but using them interchangeably just because they look alike will lead to structural problems in the converted XML.
  • Stick to the rules. Using formatting overrides—such as setting one instance of a level-1 heading to start at the top of a page but not all of them—may be allowed within your template, but that doesn’t mean it’s a good idea. These small touch-ups to the text are a quick and easy way to make your documents more visually appealing for print, but they introduce inconsistencies that will cause problems during conversion. Having a style guide won’t help unless you stick to it.
  • Avoid special formatting. Need to create a new table style for that unusual table that doesn’t fit the rules in your template? Want to control where your long titles break across lines? Wish you could align two images and add space around them to make them more visually appealing on the page? These one-off formatting adjustments may be tempting to make, but they will only cause problems during conversion. Every manual tweak that is added to the source will have to be manually removed from the converted documents, since XML is designed to separate content from formatting.

Don’t have the funds or resources to clean up your content before conversion, or can’t spare the time within your deadline-driven schedule? You can still use the conversion process to improve the quality of your content going forward.

Look for opportunities to make your content more consistent as you convert it. For example, each of your legacy documents begins with a list of parts found in that book, along with photos and descriptions. This list is structured differently from one document to the next—sometimes it’s presented in a table, other times in a bulleted or numbered list, and other times in regular paragraphs. Choose one of these options and set up the parts list the same way in every converted XML document. Set similar precedents every time you see patterns in your legacy content to ensure that the converted content is as clean and consistent as possible.

Finally, use the conversion to get your tech pubs team into the mindset of separating content from formatting, and start to break them from the print-oriented habit of adjusting pages for aesthetic purposes. Whether or not you have time to clean up your legacy documents before XML conversion, separating your content from formatting is one of the greatest benefits you will gain when you move to XML—and changing your perspective to embrace formatting-free content is one of the most important lessons you will learn.

There will be more on making the adjustment to creating content separately from formatting in part 2 of this post next month.

A hierarchy of content needs

March 4, 2014 by

Some thoughts on how to evaluate content needs as a foundation for content strategy.


In working through the idea of minimum viable content, I decided to build out a hierarchy of content needs based on Maslow’s hierarchy. In Maslow’s pyramid, the basic needs (like food and water) are on the bottom. If you don’t have the basics, you’re unlikely to be interested in the top layer (self-actualization).

What happens if you look at content needs?

Based on Maslow's hierarchy of needs, the layers are from bottom to top: available, accurate, appropriate, connected, and intelligent

Scriptorium hierarchy of content needs

The bottom three layers are what’s required for minimum viable content.

This hierarchy helps us with content strategy work. When your content is not even available in a useful format, focusing on social engagement (the connected layer) is probably premature.

Available

Available content means that information exists, and the person who needs it has access to it. If the content hasn’t been written, but the reader can’t find it, or if it’s behind a firewall/login that the reader doesn’t know about, then content fails the available test.

The first step in meeting content needs is to make the information available to people who need it. You can push information via email, publish to the web or a private site, or send out printed catalogs. But “available” is the first critical need.

In the available category, we also look at whether content is findable, searchable, and discoverable—if readers can’t successfully locate the content they need, it exists, but it’s not really available to the readers.

Accurate

Content should be accurate. Available but inaccurate isn’t so good. Under this category, we can also evaluate information for grammar, formatting, consistency, and other decorations that improve the content quality.

 

Appropriate

Appropriate content is delivered in the right language, in the right format, at the right level of complexity. This is where we put together the user’s needs with the delivery possibilities.

Content is “available” when you put it in a crappy PDF and email it on request.

To pass the “appropriate” test, you must deliver that information in a way that is best for the user. Depending on your user, that could mean a mobile-friendly HTML web site or an EPUB file. There’s delivering content, and then there’s delivering content WELL.

Connected

The connected layer is where you add user engagement and social layers. This is hard to discuss without using terrible buzzwords, but what I’m looking for here is the ability for readers to comment on your content, vote it up and down, and perhaps edit content or create their own content.

You want to support users in engaging with your content.

Intelligent

The pinnacle is content that isn’t just a static piece of text, but information that can be manipulated for different purposes.

Intelligent content might include content that is personalized, interactive service manuals, the ability to filter information based on my needs, and more.

Often, delivering intelligent content requires you to integrate database content (for example, product specifications) with authored content. Troubleshooting instructions, for example, might be integrated with information from the organization’s parts database.

Here’s a slightly more detailed version of the pyramid.

details

What do you think? Can you use the hierarchy of content needs to assess your content requirements? Do you agree with the hierarchy?

UPDATE: Hilary Marsh also built a content needs hierarchy, but hers was published in July 2013 (much earlier than this one). I don’t recall seeing her article, but it’s possible that it’s been kicking around in my subconscious mind for several months. That said, we do have some significant differences, although happily we both have “accurate” as an important base layer in the pyramid.

What I learned at tcworld India

February 25, 2014 by

Some thoughts after a trip to Bangalore for the tcworld India event.

Having experienced roughly eight blocks of downtown Bangalore, I will refrain from making broad generalizations about India.

The TWIN and tcworld teams who were responsible for organizing the event did not disappoint. They had a great roster of speakers and topics. Many thanks to them and to all their volunteers. I know that making an event appear to run smoothly requires extensive (and usually frantic) work behind the scenes.

Indian audiences ask great questions. In the US and Europe, it’s common to get a statement in the form of a question, a question designed to show off the questioner’s own expertise, or an extremely specific question that is only relevant to the person asking. (A graphic that shows the problem.) The questions I had after my presentations in Bangalore were pertinent to the topic and quite insightful. Several people did have detailed, specific questions–but they all approached me later in the event when we had time for a lengthy discussion.

Technical communicators at this event were very enthusiastic. It was a welcome contrast from the often jaded perspective we get in the US. I do hope that India’s tech comm community will not learn from their US counterparts in this area. I ran out of handouts due to an overflow audience in my content strategy workshop…but it wasn’t until I walked around the room and noticed that people were sharing handouts that I realized this. Nobody complained or inquired about the availability of additional handouts. In any other venue, at least one person would have asked, “hey, are there any more handouts??”

Some notes on culture….It appears that the etiquette rules for cell phones are different. There was no request to turn off or silence cell phones, and several people took calls during the sessions (while sitting in the session). That said, the protocol appears to be that you take a call very quietly, hunched over, with your hand covering the phone. It wasn’t noticeable unless you were very close by. Somehow, given the prevalence of Loud Talkers, I don’t really see this approach working in the US.

India is a really long way from the US East Coast. Yes, I know, DUH, but until you actually get on a plane and experience the travel for yourself, it is quite indescribable. 10:30-hour time difference, 20-30 hours of actual travel door to door. It is NOT pleasant. After arrival, I had a couple of days to get adjusted, and spent my time in useful pursuit of scarves and a lovely carpet. I’ll note that India already has chip-and-PIN credit card terminals, unlike the “advanced” United States.

Service standards in India are much higher than elsewhere. I could get used to the tea server, or the guy whose job it is to bring me my omelet from the breakfast station. (And who first told me there would be a slight wait and then apologized profusely when he delivered the food a very few minutes later.) All this wonderful service is made possible by the large number of staff. At breakfast, I eventually counted and realized that we had about 10 servers working. In an equivalent U.S. venue, I would have expected to see 2-3 harried people. In the case of the five-star “Western” hotels in Bangalore, the hotel rates are perhaps half what you would pay for the same hotel in the U.S. or Europe–high by Indian standards, but low by US/European standards.

Speaking of service, I also noticed that I kept seeing the same staffers…the guy who checked me in with a smile at 4 a.m. was still at the front desk at 11 a.m. The hostess at dinner was working again at breakfast. The lunch guy also brought up an evening room service tray. I’m not sure exactly what the shifts are, but they are definitely more than eight hours long.

Back to the conference…we’re always talking about global content, global audiences, and the like. Numerous people approached me during the event to tell me that they follow our web site. Hearing “oh, I love your web site” after a trip halfway around the world? THAT gets my attention. It also made me think…we have web site analytics, so we are aware that India is our fourth-largest readership (after US, Canada, and Germany). But charts are not at all the same thing as real live people telling me that they read our stuff.

This is why we travel for conferences; to meet people and make personal connections; to understand how a particular location shapes people’s thinking; to expand our horizons past our own community and culture.

Many thanks to the all the participants at tcworld India. I enjoyed getting a glimpse of your world, and I hope to return.

Greatest hits for your listening content strategy pleasure

February 10, 2014 by

Transitioning to new publishing processes? Release your greatest hits collection first!

Fortunately for the vocally challenged like myself, I’m not talking about songs. I’m talking about a compendium of samples representing the content moving into the new processes.

On content strategy implementations, the lack of a good file testbed is a big obstacle to thoroughly testing how well new processes work. You can use sample files provided with your new tools, but how well do those samples correspond to your content and requirements? Not at all, based on my implementation experiences.

So, it’s up to you to create a useful, relevant greatest hits collection.

Here are a few tips for developing your collection:

  • Album cover for Bach's Greatest Hits

    flickr: bjornmeansbear

    If you have content for multiple audiences, collect samples for all audiences. For example, if you have content for users and administrators, pull some sections for both groups. It’s likely that content for different audiences contains unique constructs you need to maintain in your new processes.

  • Identify common content elements as well as outliers. You probably have a core group of styles, formatting, or elements that occurs across all information types. That core will be easier to identify. What’s not as easy to figure out is what outliers you need to preserve as you move forward. Are special constructs merely overrides that rogue writers created to do things their way, or do they provide value worthy of consideration for the new workflow?
  • Album cover for Donna Summer's On the Radio

    flickr: exquisitur

    Work with someone experienced in the new workflow to adapt your samples for the new processes. As part of your move to another workflow, you may have hired someone experienced with the new tools, or maybe you have a consultant on board to help with the transition. It’s critical that a seasoned user of your new processes have a lot of input into moving your samples from the old process to the new workflow: creating testbed files from samples is not just a matter of conversion. For example, if you are moving from desktop publishing to an XML-based workflow, there are multiple combinations of XML elements you could use to create a valid version of a particular sample. However, valid content doesn’t always equate with best practices. It takes an experienced user to know the difference.

  • Exact re-creation of your samples in the new workflow isn’t always the right goal. If you’re working in a regulated industry, you probably don’t have a lot of wiggle room in how to present information. Standards dictate organization, appearance, and so on. Your sample files should therefore look the same in both old and new processes. If you’re not constrained by regulations, however, a slavish devotion to the old way of doing things may not serve you well. Evaluation and guidance from a third party—a new employee or a consultant—can help you figure out what’s working in your old content and should be preserved (and what should be banished forever).

Have you released a set of greatest hits files? Please leave your tips in the comments.

Strange bedfellows: InDesign and DITA

January 27, 2014 by

or, What you need to know before you start working on a DITA to InDesign project.

There are a lot of ways to get your DITA content rendered into print/PDF. Most of them are notoriously difficult; DITA to InDesign, though, may have the distinction of the Greatest Level of Suck™.

InDesign XML formats

InDesign provides several XML formats. InDesign Markup Language (IDML) is the most robust. An IDML file is a zip container (similar to an EPUB). If you open up an IDML archive, you’ll find files that define InDesign components, such as pages, spreads, and stories. If you save a regular InDesign file to IDML, you can reopen the IDML file and get back your InDesign file, complete with layouts, graphics, formatting, customizations, and so on.

IDML is both a file format and a markup language. The IDML language is used inside the IDML file. In addition, a subset of IDML markup is used in InCopy files (ICML). Where IDML can specify the entire InDesign file, ICML just describes a single text flow.

(There is also INX, but that format is for older versions of InDesign and has now been deprecated.)

If you are planning to output from DITA to InDesign, you probably want ICML. The IDML language is used in both IDML and ICML files. The IDML specification is available as a very user-friendly PDF on Adobe’s site. I spent many not-glorious hours plowing through that document.

My best tip: If you need to understand how a particular InDesign component is set up in IDML, create a small test file and then save the file out to InCopy (ICML) format. This will give you an almost manageable snippet to review. You’ll find that InDesign includes all possible settings in the exported file. When you create your DITA-to-ICML converter, you can probably create a snippet that is 90 percent smaller (and includes much less stuff). The challenge is figuring out which 10 percent you must keep.

Understanding the role of InDesign templates

Use an InDesign template to specify page masters, paragraph styles, character styles, tables styles, and more. This template becomes your formatting  specification document.

To import XML content, do the following:

  1. Create an ICML/IDML file that contains references to paragraphs and other styles (more on this later).
  2. In InDesign, open a copy of the template file.
  3. Place the ICML file in your template copy. The style specifications in the template are then applied to the content in the ICML and you get a formatted InDesign file.

Of course, this nifty three-step procedure elides many months of heartbreak.

The mapping challenge

A basic paragraph, in DITA, looks like this:

<p>Paragraph text goes here.<p>

The equivalent output in IDML is this:
<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/body">
   <CharacterStyleRange AppliedCharacterStyle="CharacterStyle/$ID/[No character style]">
     <Content>Paragraph text body goes here.</Content>
  </CharacterStyleRange>
  <Br/>
</ParagraphStyleRange>

Some things to notice:

  • The inline formatting (CharacterStyleRange) is specified even when there is no special formatting.
  •  The content is enclosed in a <Content> tag.
  • The <Br/> tag toward the end is required. Without it, the paragraphs are run together. In other words, if you do not specify a line break, InDesign assumes that you do not want line breaks between paragraphs.
  • Extra whitespace inside the <Content> tag (such as tabs or spaces) will show up in your output. You do not want this.
  • Managing space between paragraph and character tags is highly problematic.

Other important information:

  • You must declare the paragraph and character tags you are using at the top of the IDML file in the RootParagraphStyleGroup and RootCharacterStyleGroup elements, respectively.
  • <RootCharacterStyleGroup>
       <CharacterStyle Self="CharacterStyle/$ID/[No character style]" Name="$ID/[No character style]"/>
       ...
    </RootCharacterStyleGroup>
    <RootParagraphStyleGroup>
       <ParagraphStyle Self="ParagraphStyle/body" Name="body"/>
       ...
    </RootParagraphStyleGroup>

  • You cannot nest character tags in InDesign. Therefore, if you have nested inline elements in DITA, you must figure out how to flatten them:
  • <b><i>This is a problem in InDesign</i></b>

    <CharacterStyleRange AppliedCharacterStyle="CharacterStyle/BoldItalic">
          <Content>You have to create combination styles in InDesign.</Content>
       </CharacterStyleRange>

  • Generally, you will have more InDesign paragraph styles than DITA elements because DITA (and XML) have hierarchical structure. For example, a paragraph p tag might be equivalent to a regular body paragraph, an indented paragraph (inside a list), a table body paragraph, and more. You have to use the element’s context as a starting point for mapping it to InDesign equivalents.
  • In addition to using hierarchical tags, if you want to maintain compatibility with specializations, you must use class attributes rather than elements for your matches. That leaves to some highly awkward XSLT templates match statements, such as:
    <xsl:template match="*[contains(@class,' topic/ul ')]/*[contains(@class,' topic/li ')]">
        ...
        </xsl:template>

  • In addition to paragraph and character styles, you need to declare graphics, cell styes, table styles, object styles, and colors. (There may be more. That’s what I found.)

Tables

Tables are not your friend. InDesign uses a a particularly…unique table structure, in which it first declares the table grid and then just lists off all the cells. The grid coordinates start at 0:0. (Most “normal” table structures group the cells into rows explicitly.)

<Table TableDirection="LeftToRightDirection" Self="aaa" ColumnCount="2"
             HeaderRowCount="0"
             BodyRowCount="2"
             FooterRowCount="0"
             AppliedTableStyle="TableStyle/ExampleTable">
         <Row Self="bbb" Name="0"/>
         <Row Self="ccc" Name="1"/>
        
         <Column Self="ddd" Name="0" SingleColumnWidth="100"/>
         <Column Self="eee" Name="1" SingleColumnWidth="100"/>

         <Cell Self="fff" RowSpan="1" ColumnSpan="1"
               AppliedCellStyle="CellStyle/$ID/[None]"
               Name="0:0">
            <ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/cell_center">
               <CharacterStyleRange AppliedCharacterStyle="CharacterStyle/$ID/[No character style]">
                  <Content>first cell content goes here</Content>
               </CharacterStyleRange>
            </ParagraphStyleRange>
         </Cell>
          [...much more here...]
</Table>

As you can see, this gets complicated fast.

There is so much more, but I think you get the idea. It is definitely possible to create a DITA to InDesign pipeline, but it is challenging. If you are looking at a project like this, you will need the following skills:

  • Solid knowledge of InDesign
  • Solid knowledge of DITA tag set
  • Ability to build DITA Open Toolkit plugins, which means knowledge of Ant and XSLT at a minimum

The open source DITA4Publishers project provides a pipeline for output from DITA to InDesign. We looked at using it as a starting point in mid-2013. At the time, we found that it would be too difficult to modify DITA4Publishers to support the extensive customization layers required by our client.

Our DITA to InDesign converter is a DITA Open Toolkit plugin (built on version 1.8). It supports multiple unrelated templates for different outputs and specialized content models. It also includes support for index markers, graphics, and other items not addressed in this document. Scriptorium is available for custom plugin work on InDesign and other output types. For more information, contact us.

 

Trends in technical communication, 2014 edition

January 21, 2014 by

Our annual prognostication, along with an assessment of our predictions from last year.

2013 in review

Our predictions from 2013:

  • Velocity: the requirement for faster authoring, formatting, publishing, delivery, and updates is forcing tech comm into significant changes. This was a theme in our presentations and consulting projects this year.
  • Mobile requirements change tech comm. This is happening, but more is needed.
  • Rethinking content delivery. Again, I’d like to see more.
  • Bill had PDF continuing to thrive, and continued growth of localization requirements, along with another trend related to mobile.

Looking back, these predictions seem quite cautious, but I think that are largely accurate as trends.

On to 2014…

 

Trend 1: People like their silos.

four silos in a row

flickr: docsearls

Despite increased talk about breaking down silos, people still like them. Working in silos gives those working within them and managers overseeing them a sense of control over their content, whether real or perceived. Technology investments within individual silos will continue for the foreseeable future. This technology will need to “talk” to the technology used within other silos—using a common format—to efficiently share content. While people may like their silos, executive management is growing less fond of them, regarding them as roadblocks to collaboration and contributing factors to excess overhead costs. Looking forward, we will start to see technology investments across or outside of silos that further centralize content management and ease the burden of reusing content across groups.

 

Trend 2: Reorienting toward a customer perspective of content

looking down into a silo

flickr: neurollero

Organizations are beginning to look at content from the customer’s point of view. Customers just want information; they don’t care about the internal differences between a knowledge base article and a topic from tech comm. As a result, the pressure to integrate these diverse roles and deliver unified information (usually to the corporate web site) is increasing. Executives are aware of these issues, and they do not want to hear about how the internal structure of an organization makes it problematic to deliver what they want.

 

Trend 3: Blurring of tech comm, marcom, and content strategy

blurred silos at night

flickr: mahalie

The term “content strategy” has been heavily used by those working in tech comm and marcom over the past few years, though the focus has differed. In the scope of tech comm, content strategy primarily involves the process of creating, managing and producing content. The marcom focus of content strategy has traditionally been on audience engagement. The line between these two camps is now blurring. Tech comm is increasingly interested in and responsible for tracking the effectiveness of content, and marcom has an increased awareness of the content management lifecycle and of localization requirements. We’ll see an increase in collaboration between tech comm and marcom as the lines continue to blur, and perhaps a new discipline will emerge as the trend continues.

 

Trend 4: Apps are winning over HTML5

brick silo

flickr: tinfoilraccoon

This one requires context. A lot of our customers are building apps for their content. In particular, they are using apps for information that is delivered to staff technical support or field services people—employees who go to customer sites and install or fix things. For that specific use case, most companies are opting for an app because:

  • The company provides the employee with a device (usually a tablet) with the technical content. As a result, the target device is known—the company can create a single app on a single operating system.
  • They want functionality, especially integration with other systems, that is easier to achieve with an app than with HTML5.
  • They like the control provided by the app update process.

Does this fly in the face of the bring your own device (BYOD) trend? Yes, it does.

 

Trend 5: Lots of creativity in output—not source

Silos with art and a QR code

flickr: cstreetus

Business and consumer demands drive content requirements, and the rate at which these demands change is increasing. New apps, new delivery formats, and new use scenarios are constantly introducing new requirements. To respond to these evolving requirements, content developers will need to get creative on the output side while standardizing on a simpler, cleaner source. This will ensure that content is poised and available for transformation and production to required formats.

 

Trend 6: Content can be an asset—or a liability

Looking at sky from inside silo

flickr: alisonpostma

Like other content strategists, we have been arguing for some time that content is a corporate asset and should be managed properly. But “content is an asset” doesn’t tell the whole story because the corollary is that:

Bad content is a liability.

Organizations are beginning to recognize that their content can help or hurt them. They ignore content at their peril.

What do you think of our trends? Did we miss one?