June 2011
By Mathew Varghese

Mathew Varghese is the Content Architect for the Networking and Cloud division at Citrix. He is an ardent DITA evangelist and a staunch supporter of the open source movement. He is currently developing a DITA-based information architecture methodology.


mathew.varghese[at]citrix.com
www.citrix.com

Moving to DITA

Although anticipating its potential, managers often fear the shift to DITA. As the Tech Pubs Team at Citrix’s Networking discovered, the move is indeed a lengthy and sometimes complex one, but the long-term benefits may entirely justify the effort.

In 2007, I participated in a content management conference in New Orleans, where I bumped into DITA gurus Robert Anderson and Michael Priestly. Up until then, as the Tech Pubs manager for Citrix’s NetScaler® product line, I had been trying to solve content management issues by tweaking Adobe® FrameMaker® and Microsoft®Word. I was looking for a solution that would allow our content developers to create reusable pieces of information that could be combined to produce whitepapers, presentations, articles, product documentation, and so

 on. After listening to Robert and Michael, I realized that DITA was the perfect content management solution for us. What persuaded me was DITA’s emphasis on semantic tagging and modularity—key ingredients for good content management. The freely available DITA Open Toolkit provided a compelling reason to at least try it out.

DITA was so easy to adopt that I had to fight hard against the urge to dive right in. The sample files bundled with DITA OT made it very easy to try out. However, I wanted to make sure that we understood what we were getting into, because of our tight release schedules. The economic downturn was already upon us, and we had to deliver real results. The executives obviously had no time or patience for experiments. So, to measure the benefits of adopting DITA in an objective manner, we decided to define our requirements.

Defining requirements

Most of our requirements revolved around the issues we were having with our existing publishing setup. We weren’t really looking to replace anything in a major way, but we were willing to make small changes. Here's a list of changes that we wanted to make to the publishing setup:

  • Seamless support for single-sourcing
  • Automated publishing
  • Integration with the software build system
  • Integration of review into the workflow

Once the requirements were defined, we decided to try out DITA in a controlled production environment.

Running a controlled pilot project

Our pilot project was a cross-functional effort involving teams from support, documentation, and education. These teams had been collaborating, so it made sense to use content collaboration as a primary use case for DITA adoption. The teams were distributed across the U.S. and India. We began the pilot project in 2008.

The main goal of the pilot project was to create a common repository of DITA topics and generate different deliverables by reusing the topics. For the pilot project, we decided to create a 10-page user manual, a Microsoft®PowerPoint presentation, and a training-session handout. The volunteers, recruited from the participating teams, would create the topics and DITA maps for their deliverables. We also planned to use ditaval to profile the topics.

The project took 3 months to complete. We had regular meetings and exchanged ideas, but the project was not a success. We did manage to create the user manual, but the presentation and handout never materialized. So what went wrong? To begin with, while all the participants understood DITA in principle, they did not have good authoring tools. Most XML editors we had then were code editors, and content developers did not like that interface. They wanted WYSIWYG editors. Our second big issue was the lack of an information model. In the absence of rules for scoping topics, writers created DITA files that were not reusable. Last but not the least, we sorely missed a good production person – someone who would create the deliverables for us and troubleshoot all the DITA OT issues.

Despite our inability to generate the deliverables, we all were convinced of DITA’s usefulness. Ditaval-based profiling worked wonderfully and amazed the executives. We also realized that our inability to reuse topics was due to our own lack of knowledge. So we decided to go ahead and move to DITA, but gradually. The team disbanded, and we all began to work separately on our DITA initiatives. The Tech Pubs effort began with building a publication team.

Building a publishing team

To implement DITA effectively, we in Tech Pubs first decided to develop Information architecture and publishing expertise. For nearly a decade, the structure of the writing team was similar to that of other technical writing teams in the industry. We had a manager, an editor, and several writers. This wasn't a very efficient configuration, because writers often spent a lot of time on publishing their deliverables. So, while we were very keen on building a publishing team, we didn't have a very strong business case. The benefits of DITA, however, provided us with a strong business case for building a publishing team.

Our move to DITA began in 2009. I moved out of my role as a manager to become a content architect for my division. I would henceforth focus on Information architecture and content strategy. Later that year, I recruited two interns to help me with publishing and tool development. I had previously begun working with our editor to define processes and standards.

Defining processes and standards

Our senior editor, Don, and I began work on processes and standards toward the end of 2008, and our work continued through the first half of 2009. While Don worked on the writing guidelines, I worked on developing an information model, semantic tagging guidelines, and the information development process. During this period, the writing team remained undisturbed, with the writers continuing to work in Adobe® FrameMaker®.

Our first deliverable was Don’s structured-writing guidelines, which explained how to start incorporating principles of topic-based writing and minimalism in our existing documentation. By June 2009, I published the semantic tagging guidelines, which listed all the DITA elements that writers could use and where they could use them. However, most writers would not use these until much later. The initial round of conversion (of FrameMaker content to DITA) was done by the interns. By Q3 of 2009, I published the new information development process that clearly demarcated the roles of the writers, the information architect, and the publishing team. A key aspect of the new process was the emphasis on analysis and design. We introduced a new practice requiring writers to first present their information design to a review panel before authoring content.

The structured-writing guidelines, semantic tagging guidelines, and the new authoring process with emphasis on analysis and design provided us with a firm foundation for implementing DITA.

Getting started

We officially started the project in May 2009. Our aim was to build a repository of DITA topics and reuse them effectively—never to merely convert the product documentation from FrameMaker to DITA. We did rewrite the documentation in FrameMaker, but in a structure that facilitated conversion to DITA.

Our first project involved converting just one small guide to DITA. We did that for three reasons. First, we wanted to test the guidelines and processes that Don and I were working on. Second, we wanted to train our interns in semantic tagging and the authoring environment. Third, we were under pressure to deliver. Most of the other writing teams in Citrix had already moved their content to DITA, and we were just getting started.

Our first project was a huge success. It took us less than two months to restructure, rewrite, and publish a 120-page manual. We owed part of our success to the team at the Citrix headquarters that had set up the CMS and the authoring environment for us. This project taught Don and me several important lessons, and we incorporated them in our standards and guidelines.

Stopping and calibrating

After our first successful attempt, we stopped to review our standards, guidelines, and processes. While we seemed to be proceeding in fits and starts, we were actually calibrating our guns without firing them too many times. We had two very good reasons. First, we needed to optimize the writing team’s time. We have nearly two releases a year, so the writing team is always busy. Therefore, while everybody agreed that the docs had to be reorganized and rewritten, I had to find a relatively quiet period in which to get it done. Second, we had to make this a win-win situation for the writers. Rather than rushing them through the migration process, we wanted to train the writers thoroughly. Minimalism, topic-based writing, and semantic tagging were new to most of the writers. The authoring environment was new too. So we decided to train the writers on the new writing paradigm but not the tools – the interns would be trained on tools.

Don and I finalized the standards, guidelines, and processes by Q3 2009. I had hired the interns, Arun and Anirudh, by August, and the stage was set for us to get cracking. The writing team, however, was still busy with a major release. So we started by converting reference material and legacy content to DITA. This gave the interns valuable on-the-job training. During this time, I firmed up the information development process and the project roadmap.

Steaming ahead

For nearly 7 months, Don and I had worked part-time on this project. So, from a management perspective, that was not a great overhead. The final stage of the project was something else altogether. This time, I would be engaging the entire team. Time management was of paramount importance. My strategy was very simple: I aligned all project milestones with the product release milestones such as beta and GA. Then, we concentrated on content for the key product features. These strategies ensured that the team received all the visibility and feedback that it deserved in a timely manner.

By this time I actually stepped on the gas, it was Q4, 2009, and we were hoping against hope to complete the project by Q1, 2010. Unlike the writers, Don and the interns (Arun and Anirudh) were already steeped in DITA and the authoring environment. Getting the writers to hit the road running was a challenge, but on-the-job training and careful monitoring finally did the trick. Don spent hours and days doing content edits and providing copious feedback. Sometimes I suspect that he wrote as much as all the writers put together. The number of topic collections was so great that I delegated the job of tracking them to Arun and Anirudh, since they were directly working on them. It was their task to keep the project plan updated, and they did a stellar job. The writers bore the brunt of the entire project though. They had moved from one stressful project to another with no break, but they bore up very well.

Moving away from the book paradigm was not easy for the writers. Instead of owning books, the writers now owned feature sets, and they were supposed to build topic repositories for these feature sets. The topics would then be strung together, using DITA maps, to create different deliverables. The deliverables, including PDF manuals, would now be created and published by the newly formed Production and Tools team. We also introduced a new process called Design Walkthrough, in which writers would research their features and then design DITA maps for their topic repositories. This map would then be reviewed by a panel. Once the panel signed off the design, the interns would create the maps and stub files while the writers would rewrite the content as required by the structured-writing guidelines. After the writers had finalized their content, the interns would update the DITA topics and generate the deliverables. All the rewritten content was posted on eDocs, the Citrix’ product documentation portal, and as PDF manuals.

By Q4 2010, we also developed our own online help system, which uses DITA topics. We also used ditaval extensively for profiling our content. By developing our own information model and by using ditaval, we were able to publish the same set of topics in different formats and reuse topics across deliverables and releases.

Settling down to a new reality

Nearly two years ago, ours was a regular technical writing team. As a manager then, my biggest challenge had been to utilize my team’s time more effectively. Back then, most writers spent over 20% of their time on publishing activities such as generating PDF files and online help. With the Production and Tools team handling all publishing work, that number has now come down to less than 5%, and we hope to reduce it even further. Writers today spend more time on analysis and design. They also spend more time in face-to-face interactions with engineers and product managers to better understand the audience and the product. In addition, writers and editors get to spend more time on reviewing the documentation. Thus, increasing the team’s productivity has led to the improvement of the overall quality of the documentation.

To adopt DITA, we had to adopt minimalism and topic-based writing practices. This has benefited other teams in addition to ours. Due to the modular nature of the content developed by the documentation team, other content development teams find it easier to reuse and repurpose it. As a result, there is now greater collaboration with other content development teams.

With the Production and Tools team handling all publishing activities, the writing team has begun to participate in several cross-functional activities. These include editing whitepapers for the marketing team, writing blogs for community sites, and creating screencasts for the engineering and support teams.

Conclusion

The move to DITA has been a very exhilarating one. It feels great to be a part of a revolution that promises to change the content development industry. There is an upfront cost to reorganizing the team and procuring new tools, but those costs are amortized over a relatively short period of time. What’s more, there are several non-profit groups promoting DITA, and they can help you with your move. These include the OASIS DITA Adoption Subcommittee, the DITA Adoption Asia Subcommittee, and the dita-users Yahoo group.