Best Practices from the Outside In


August 2009

Managing Metadata for Responsive Web Sites with Subject Schemes

CIDMIconNewsletter Sarahjane Clark, SDL XySoft

This is the story of a small technical documentation group in a content management company and how they made the move to DITA and lived to tell about it.

Let me start by introducing my technical documentation group. We are two full-time writers. That’s it! Both of us have extensive FrameMaker experience and one has experience with topic-based writing, minimalism, DITA/Docbook, and content management.

Our team is not unlike many technical documentation departments—there never seems to be enough time to address the growing number of product releases and increased time-to-market pressures. And like larger tech doc teams, we recognize and get excited about the same opportunities for content reuse, whether it’s among departments, across product lines, or even across platforms.

So Why DITA and Why Now?

There were three primary reasons why we chose to go down the DITA path. First, our documentation was in multiple formats—FrameMaker, Word, and proprietary. Additionally, we had stored this documentation in a variety of places. By consolidating the formats and storage locations, we knew it would not only save time during a release but allow anyone else to step into the group to help develop content.

The second reason to go down the DITA path was to take advantage of the obvious reuse both within a product release and from one product release to the next. This reuse potential makes us much more efficient (which is key when working in an Agile development environment) and allows us to support a large and disparate user community.

Lastly, it allowed the use and expansion of a contractor pool. Supporting legacy formats, and getting a contractor up to speed on them, can suck up bandwidth while multiple storage systems require longer ramp-up time for a contractor to begin working with the data.

So how did we determine what should be authored in DITA and what should remain in a legacy format? We went right to the source—our customers. We interviewed the end users of our products and peeked at the documentation they use with the software every day. In many cases we found the documentation was marked-up, highlighted, contained sticky notes, had whole sections removed, and was dog-eared. The one resounding theme we heard was, “Tell me just what I need to know.”

Tell Me Just What I Need to Know

Many customers told us that when it comes to an installation guide, it’s often their IT department doing the installation—not the product person or end user of the solution. So including specific product detail is lost on them. Should an IT person care about point or pica size for publishing composition software? Likely not. But a publishing manager would expect to find this level of detail in the user guide.

Now I’m not talking about customized documentation—that’s a whole other application, and an article for a future newsletter. Rather, I’m talking about finding out how most customers work, then building the document for a specific audience based on their goals and everyday tasks.

DITA is an ideal conduit for this approach as it lets us write topics for all the tasks and goals that all our users have, then assemble them into individual documents that match what a particular role, like an installer, needs to accomplish. As a result, we give the readers just the topics that address the goals they’re interested in.

One Step at a Time

Converting documentation into DITA can appear to be a Herculean task. So what is the best approach? I recommend you take it one step at a time—be it one book, one release, or even one topic. Put on your minimalist glasses and make an initial edit pass. Mark up whatever doesn’t need to be there. You’ll be surprised by just how much information is extraneous and how manageable the remainder becomes.

Here are some examples of superfluous content we’ve removed from our manuals and that I’ve seen customers delete from their own printed documentation:

  • Promotional product information that appears in front of many manuals
  • Instructions or explanatory information that is intuitive or doesn’t add any value.
      * For instance, after every single instruction, do you really need a follow-on sentence that says “the xx window will appear”?
  • Screen shots of welcome panels in wizards

There are several factors involved in determining what content should get “DITA-ized.” These are a few that I think about when planning a documentation release:

  • Select content of a reasonable size. “Reasonable” varies from release to release but always takes into consideration available time, number of user goals/tasks, and available resources.
  • Consider smaller books that require a major overhaul
  • Look at larger books that can be done in phases (perhaps over two releases or one part in a beta phase and the remainder for the released product)

Consider implementing DITA and minimalism in a phased approach, and if possible, with new documentation. These choices help to prevent any shock to the current users of your documentation who may have grown attached to a plethora of details, useful or not. This method also allows you to build credibility since one successful small doc set can attract a lot of positive attention and pave the way for the conversion of larger documentation pieces, and can ultimately provide the foundation for a fundamental shift in the way that your users consume content.

Frame It Until You Make It

Many companies would like to take advantage of all that DITA has to offer but are reluctant to start because they’re unwilling or unable to commit to the time and resources needed to ensure a successful implementation. What they may be unaware of is that it’s possible to make the migration to DITA without breaking stride and losing productivity.

Since the advantages of FrameMaker are proven and the benefits of DITA are measurable, the question is often not if, but when…and how? When the deployment of a CMS is thrown into the mix, the advantages of adopting a phased approach are even more compelling. This method provides the best of both worlds by allowing you to ease into a structured content management environment without disrupting the editorial workflow and familiar tools that you’re comfortable using. By minimizing your content, chunking it into individual FrameMaker files, and uploading it to a CMS you can realize the benefits of version management, workflow, search, and reuse—just to name a few—without having to learn a new editorial tool. This strategy minimizes the amount of disruption to people and processes and reduces the need for retraining. Also, depending upon your CMS, your FrameMaker data can co-exist alongside your DITA data in the same repository.

Be Careful What You Wish For

Converting legacy content to DITA, even just a few pieces, makes it easier to hand off to a contractor. If your CMS is tool-agnostic, then DITA can be supported by a number of editorial tools. But wait. How do adding additional formats and storage requirements address the initial problem? Well, you have to start somewhere. One successful DITA document migration breeds another, and soon you’ll see greater attention being paid and more resources being allocated. I witnessed this snowball effect in action in my own organization as well as at several customer sites. Soon everyone was jumping on the DITA bandwagon and the bigger challenge became scheduling.

What Comes Next

Once you’ve mastered the creation of DITA content, there’s a whole world of possibilities for dynamic content delivery. Remember how we talked with our customers to learn about how they work, what their roles are, and what they really want to read about? How about taking DITA content and serving it up by a user’s role, skill level, language, or area of expertise to make the content come alive? Using a delivery vehicle like an Interactive Electronic Technical Manual (IETM) allows a user to interact with the data, providing an even greater degree of customization and self-sufficiency. Add in a closed-loop reporting system and now your end users can report any errors or suggestions back to the content creator, ensuring the content is always timely and accurate.

So looking from the outside in, would I do this all over again? You betcha. I only wish we had started sooner. CIDMIconNewsletter

To learn more about SDL XySoft (formerly XyEnterprise) and how you can leverage the power of a DITA Component Content Management solution in your organization, please contact us at We also encourage you to follow us on Twitter at

About the Author


Sarahjane Clark
SDL XySoft

Sarahjane Clark is Senior Technical Writer and DITA Specialist for SDL XySoft (formerly XyEnterprise).  She brings to her role over ten years of technical publications and user assistance experience in such disciplines as knowledge bases, internal training, user manuals, online Help, and interface design.  Sarahjane is currently leading the charge with SDL XySoft’s documentation, converting a variety of legacy formats to DITA.  Her work with product documentation will result in the first electronic delivery of documentation using the company’s flagship product, LiveContent (formerly ContentaView).  Prior to SDL XySoft, Clark was a Principal Information Developer at Symantec where she led a team of writers through a pilot project converting unstructured FrameMaker to DocBook.