February 2008

Roadmap to DITA

CIDMIconNewsletterAnna Hartman & Judy Kessler, Sybase, Inc.

By now, you probably know that DITA helps you organize and reuse topic-oriented content by means of DITA maps. But if you are going to move successfully to DITA, you also need another map: one that your team can follow as an organization to reach your goals.

Why are You Going There? Identify Business Reasons

Before you start heading down that road to DITA, have a clear understanding of why you are going there in the first place. Does it sound interesting? Did management foist it upon you? Be sure you can clearly define the business drivers that impel you towards a DITA solution. Otherwise, you might start heading in the wrong direction or run out of gas before you reach your goal.

At Sybase, evolving product offerings are our primary driver. Instead of standalone products, the business is moving toward a set of components that are regularly reshuffled into suites, platforms, and other solution-oriented customer offerings. On the documentation side, our independently written, product-specific books and online help made it impossible to maintain and deliver appropriate content in this new universe. We were single-sourcing deliverables from our structured FrameMaker books but needed greater flexibility to do so at a more granular level. Technical publications teams are also required to service more products and more frequent releases with the same number of writers. Reusable DITA topics became the basis of our solution.

Who’s on the Bus? Identify Stakeholders

Early on, we realized that it is not just information developers and their managers who need to be involved in our move to DITA. Just as we did, you will need to identify your

stakeholders and get them on board:

  • Subject matter experts often have strong ideas on how information should be organized and who determines that organization. But reviewers like the idea that with topics, in the long run, they will save time.
  • Marketing determines product direction and overall customer experience with products.
  • Program or project managers put the whole package together and are responsible for the schedule. They know a product is not just code dropped onto a CD.
  • Executives hold the purse strings and control staffing levels and allocation. They care a lot about customer satisfaction levels and schedules.

We gained the executive sponsorship we needed by providing research-based estimates of savings in bottom-line numbers and value to customers.

Who’s Driving? Create a Dedicated Team

We began with a small tools team to identify and adapt tools for converting, editing, processing, storing, and delivering content. As the initial tool set reached completion, we realized that authors needed more than tools. We created a transition team to develop guidelines to make this work. The tools team develops the features, and the transition team helps the users to get going on the system.

Try to schedule resources so that at least one person can be dedicated to the DITA effort full time for at least 6 months. Then beg, borrow, or steal to help flesh out the rest of the team. For example, most of our tools team is composed of writers with an interest in technical subjects. We started with a small team and have expanded as requirements have increased in size and complexity.

First Stops: Select a Pilot Project

Start small. Select a writing team that is amenable to change and has a large degree of technical savvy and patience.

Develop conversion and transformation processes

Conversion is a multiphase process:

  • Perform pre-conversion tagging and content analysis to assign existing book elements to DITA concept, task, and reference topics.
  • Write scripts.
  • Run scripts to convert legacy content to DITA.
  • Clean up converted content.
  • Transform topics by splitting, rewriting, or deleting superfluous information.

To aid in this process, consider reorganizing or rewriting the legacy content before the conversion. For example, if you know that certain chapters or features are no longer relevant, remove them before conversion.

For subsequent projects, keep a conversion plan to define priorities. We revisit it quarterly but you can do what works best for you. Product managers and release schedules set the priorities, and sometimes you must be flexible to meet rapidly changing product release schedules.

We have done the bulk of our conversions in house, for our library of legacy structured FrameMaker books based on our own techdoc DTD and our docbook-based XML content. We chose a third party vendor to do unstructured FrameMaker conversions, which were essentially one-off projects. Choose an approach based on the skills and availability of your staff and where you can get the best return on your investment. Remember that it is an investment in skills as well as cash.

How Will you Get There? Define Tasks

Here are some crucial ones. Don’t skip them in your rush to get quick results.

Define requirements

Using the business drivers as a starting point, define requirements. Talk with the lead of the pilot project to determine specific output types and other needs. This discussion can go a long way toward ensuring the success of the pilot project.

Try to stick to the requirements, prioritizing when necessary and adding members to the team if warranted. Track bugs, using bug tracking software if available. For subsequent projects, it is important to define a solid workflow so the tools team is not overwhelmed with change requests. Track everything to the plan.

Create design documents

Have the technical team author both high-level and detailed design docs to be reviewed by members of the pilot project and/or the person coordinating the DITA effort. Continue tracking everything against the requirements document so you can manage scope and keep frustration to a minimum.

Create a documentation and training plan

Have the transition lead author a documentation and training plan. Again, have internal stakeholders—pilot project lead, management, advisory team—review your plans to determine that requirements will be met. These plans are the design documents from the transition side.

Our authoring guidelines are written entirely in DITA. The two images in Figure 1 represent our top-level map and high-level topics in the largest second-level map.

Kessler_Figure 1

Figure 1: Sybase Authoring Guide DITA Maps1

What’s on the Radio? Foster Communication

Create a web site, blog, wiki, or anything to which your tech pubs department can refer for information about the project, about DITA, and about what to expect when it is their turn.

For larger, dispersed organizations, consider setting up one or more advisory teams to help you define requirements, resolve any conflicts that may arise, and evaluate results. We recently established a series of councils that address issues of information architecture, usability, models and templates, style, and terminology across the enterprise.

Are We There Yet? Define Milestones

Milestones are balanced between how quickly you can get all the plans, tools, and training together, and when they are required for projects. We recommend a phased approach. Table 1 defines our phases.

Kessler_Table 1

Table 1: Sample Phases for Moving to DITA

Where are we Now? A Fully Functional DITA Environment

We now have a system that stores content in a source control repository, employs both local and server-based build systems, an XML editor for authoring topics and architecting maps, XQuery-based searches, and the DITA OT to drive builds. The distributed team uses virtual machines to access the central repository and mitigate performance issues.

Where to Next? CMS

We are rapidly outgrowing the original system, and scalability is an issue. After researching and evaluating CMS vendors and applications, we have selected one. The next step for us is to implement the CMS to help manage the large numbers of content files in our portfolio now that our books have been split into reusable DITA topics.

Where does your road lead? Your path may vary, but many of the milestones and guideposts will be similar. Start by knowing where you are headed and why. Plan your project carefully, staff it appropriately, and invest in training as well as tooling. Identify the sights to watch for on your roadmap to DITA. CIDMIconNewsletter

1 Sybase Authoring Guide DITA Maps © Sybase, Inc., 2006-2007 All rights reserved. Sybase is a registered trademark of Sybase, Inc. All other company and product names mentioned may be trademarks of the respective companies with which they are associated.

Anna HartmanAnna Hartman

Sybase, Inc.

Anna Hartman, Senior Software Engineer at Sybase, Inc., has been involved in technical publications for the last 17 years, including positions as a technical writer for both hardware and software and as a technical writer/editor for the USGS. For 8 years, Anna has worked for Sybase, Inc. as a Staff Technical Writer. Two years ago, she helped to create a new department, Technical Publications Solutions, whose main purpose is to define, build, and maintain a DITA-based authoring system and output mechanism that meets the requirements of all Sybase® Tech Pubs teams. She presented at Content Management Strategies 2006 and 2007 and at DITA 2007 West.

Judy KesslerJudy Kessler

Sybase, Inc.

Judy Kessler, Staff Technical Writer at Sybase, Inc., has more than 30 years of experience in software documentation, as a writer, editor, and manager in the US and abroad, joining Sybase in 1998. Currently, she serves as Transition Lead for Sybase’s move to DITA, responsible for developing guidelines and training for information architects, authors, and managers, leading pubs advisory councils, and advocating for DITA throughout the organization. She has presented at the Boston DITA User’s Group, Boston STC, CIDM Showcase, and Content Management Strategies 2007.