Kristina Brinck, Xylem Inc.

The Xylem Technical Documentation Group consists of ten content developers and six persons responsible for development and maintenance of processes, standards, tools, training, support, and localization. The members of our group are placed in different sites in England, India, Sweden, and the USA. We all share the same system:

  • A tool set supporting documentation, translation, and terminology handling
  • Standards for analyzing, structuring, and presenting information based on DITA, Information Mapping, Minimalism, International Standards, internal requirements, and translation requirements

We have migrated product documentation for pumps, mixers, water treatment systems, monitoring and control equipment, valves, and accessories. Our customers, the Xylem brands representing a variety of segments and markets, often operate almost as separate companies within Xylem. Some brands own and develop a great variety of product series, with designs and materials aiming to work for different purposes in different media. An integration project is therefore sometimes required even for a series of products. The integration may require adjusting systems, processes, resources, and mindsets to work together, plus migration. The legacy materials are rarely of a quality that can simply be converted, so the migration means that we restructure, reuse, rewrite, and translate all content into our system. As with any kind of project, obstacles occur on the way; we use them to improve our routines. I would like to share some of our experiences from projects that have resulted in the integration plan we use today.

Our First Experiences

In 2009, we used vendor suppliers to migrate content for 3000 pump and mixer manuals, including language versions. This sequence of activities shows how we prepared for the migration of the legacy materials:

1. Extracted terms from legacy materials and developed a terminology database
2. Classified the products to prepare the CMS folder structure and topic metadata
3. Performed a reuse analysis of all legacy documents to estimate time and cost for the migration
4. Defined Personas, typical end users per user situation
5. Performed a generic task analysis to verify that the content and content structure would meet the Personas’ needs and conform to International Standards
6. Provided training and steering documents to the Information Architects and Technical Writers
7. Informed stakeholders about our new approach to content structuring, roles, and responsibilities
8. Kicked off the project teams and introduced our processes and expected results to the Subject matter Experts (SMEs)

Every week through the migration process, the vendor Project Managers, my manager, and I followed up on the status of each project. We used a list with the following actions to follow each project stage-by-stage:

1. Completion of the Task Analysis and the Annotated Topic List per project
2. Approval of the Task Analysis and the Annotated Topic List per project
3. Graphic conversion
4. Authoring
5. Editorial topic review
6. SME topic review
7. Topic updates
8. Output review and approval
9. Translation and publication

Lessons Learned

Soon, we found that bottlenecks appeared mainly in stages where SMEs were expected to act. They were often enthusiastic about the migration, but had issues related to time, their own work tasks, and urgency:

  • Most of the SMEs were Engineers with responsibility for product development or servicing after-market customers; they planned their time according to the product development and release schedule.
  • Our migration projects had no project code and, for many SMEs, the project code was their job ticket.
  • We migrated manuals for existing products that were out on the market and already had manuals. Reviewing these did not seem very urgent from their point of view.

We also realized that we needed to improve our processes to better support our reviews.

We had expected every topic review to go through our Content Management System (CMS) review functionality. By using the CMS for reviews, we would all be able to monitor who had added which comment, if there were any contradicting comments, and if the comments resulted in changes to the topics. But people were used to reviewing and commenting on paper copies and were reluctant to work in the CMS. One reason was the technology was still slow at the time; another reason was that we had provided the training too far in advance so the SMEs had forgotten what they learned at the time for their reviews. We learned SMEs are more likely to add annotations through the CMS if they received their training at the time for review and if they reviewed the first few topics with the writers.

When we received comments from SMEs, they were sometimes ineffective; comments like “No, that’s wrong!”, or “What about vibrations and lifting?!” needed to be followed up. Today, we have guidelines for how to comment with clear instructions.

At the output review stage for two projects, SMEs and stakeholders met the new content structure, look, and feel with dismay. They had forgotten our early demonstrations on how and why the content would be changed. We helped the SMEs and stakeholders to verify that no important content had been omitted, only restructured and rewritten. Today, we discuss the changes more frequently during the migration. The more we migrate, the greater the chance that, at an early stage, we can show sample manuals with the same look and feel as their own manuals after migration.

Information, Agreements and Training

The experiences from our migration projects in 2009 taught us to fit in information, agreements, and training closer to the respective integration stage and to add them as actions in the project planning. All together, the operational work, information, agreements, and training occur in an action list that roughly can be summarized in the following stages:

1. Prepare the new organization for the change
2. Prepare for the migration with the Technical Documentation Group
3. Kick off an Information Architecture team to review/revise the Information Model
4. Run a pilot
5. Evaluate the pilot
6. Customize the environment where required
7. Prepare for the migration
8. Perform the migration
9. Define the level of maintenance and number of new projects


The migration of new information is initiated by brand or department managers. They are generally aware of our success stories. The potential cost savings in production and translation, which are relatively easy to measure, are very convincing; what we need is their buy-in of the new processes, roles, and responsibilities that are required for the migration, and a budget. All Technical Managers must understand what is expected from their staff and inform them before we can move to the next stage. If the brand has its own technical writers, they must commit to work according to our standards; we commit to provide training, user licenses, reviews, and any other support.

The Technical Documentation Group collaborates with the brand’s key staff to get a realistic budget and time plan for the migration. The initial reuse analysis helps us estimate how many projects are needed to integrate product documentation for a brand and how much production will cost. The number of integration projects depends on the number of product types and their design and application. If the quality and structure of their legacy manuals vary greatly, the potential restructuring can be identified through a classification of the products.

The Project Planning

Once we have a budget and a project team of key persons from the brand organization, we can start the project planning. By identifying where issues appear in the documentation processes before the migration, we can set up goals and a specific business case for each brand. The goals and business case are the basis for how we rework the generic Integration Checklist to develop a specific Integration Project Plan. Each stage in this list has a default set of sub steps that we discuss: some of these sub steps can be omitted if not needed and other steps may be added. Then we develop our follow-up action plan by adding expected dates plus names of those responsible and assisting in each step (see Figure 1).


Run a Pilot

We have experienced confusion on what a pilot is and what is included. A pilot is only needed when a new product type is to be integrated to our system or when special requirements apply. Pilots should not be expected to publish final documents, but to fulfill two purposes:

  • Learning, understanding, and testing the system: Any new SME or content developer gets the training and support he or she needs to start using our standard methods and working environment.
  • Evaluating the system and the result: The process, tools, decision chains, and output are evaluated, leading to an approval or an action plan for improvements before approval.

We typically create a separate worksheet for the pilot to stress where it starts and where it ends and to make follow up easier for other actions that are going on in parallel to enable the migration. This worksheet is a simplified example of an action list for a pilot when both content developers and SMEs are unfamiliar with our system:

1. Training: Methods and standards
2. Training: Tools
3. Training and action: Set up the folder structure
4. Training and action: Set up the workflow in CMS
5. Create a limited amount of content and push through the workflow
6. Training and action: Topic reviews
7. Topic update
8. Training and action: Creating PDF’s
9. Training and action: Sending content for translation through the Translation Memory
10. Complete the pilot evaluation

The Migration

The migration can take part when the system is adjusted as defined in the pilot evaluation and when we are all ready to produce and publish the deliverables. The brand organization has set up a priority list of all products to be migrated per project, provided names of SMEs, and committed to their responsibilities through the projects.

After kick-off, we follow up on the actions with regular meetings with the project team to ensure the migration works as planned and to agree on measures to support the progress (see Figure 2). The migration project gets its own production worksheet in the integration plan.



Moving from desktop publishing to DITA should be regarded as a major change process rather than simple content handling. Enabling topic reuse and translations through our systems requires new roles and responsibilities and new competences and mindsets. By combining the necessary operational actions with information, agreements, and training in a particular order, we have managed to prevent many pitfalls in our later integration projects.

We still use a simple Excel file for our project plans, and we still expect to learn from mistakes, but the template we have today works as a more efficient tool for communication through the different stages of the migration.