Using Keys and Content References to Create Customizable Products

Home/Publications/Best Practices Newsletter/2015 – Best Practices Newsletter/Using Keys and Content References to Create Customizable Products


If you would to view this article you will have to become a CIDM Member.




This page is limited to members only. Subscribe to gain access!




June 2015

Using Keys and Content References to Create Customizable Products

CIDMIconNewsletter Peyton Bentley, Kaplan Professional Education & Amber Swope, DITA Strategies, Inc.

Have you ever had the experience that people don’t feel comfortable using your documentation system and processes? Would you agree that this could be an issue at the integration stage?

When I started working at Xylem Incorporated (formerly ITT) ten years ago, I was curious how far I could bring what I had taught customers as a consultant. The progress we have made is far greater than I could ever have imagined. This progress has not happened without obstacles. Being early adopters of DITA and stakeholders of the systems we use, we survived and succeeded by learning from all the obstacles we have run into.

Accomplishments so far

Since 2008, the Xylem Technical Documentation Group (TDG) has handled the migration of more than 6,000 outputs together with over 250 project teams placed in sites around the world. Conversion into DITA has never been an option; the legacy materials are always far too divergent to set any standards. Our routines and authoring standards serve to ensure high reuse and low translation costs and to present high-quality content relevant to the end user. One could argue that these standards are too complicated, but the payback is immediate:
We currently have our content translated into 41 languages.
About 90,000,000 words have gone through the translation process. If reuse and translation memory had not been in place, Xylem would have spent USD $9,500,000 on translation of these words. Since we do have our system in place, this cost has been reduced to USD $1,000,000.

Additionally, these results are worth noting:

  • Since we apply minimalist authoring and have an average content reuse of 70 percent, the content in our repository serves a greater amount of outputs than has earlier been possible.
  • The same size staff that served product documentation of one single brand in 2007 serves 95 percent of the 37 brands included in Xylem today.
  • At some sites, engineers spent up to 30 percent of their time writing manuals and administering translation requests of each update before using the TDG services. They still need to provide source information and review topics for technical data, procedures, and warnings, but their former tasks of documentation maintenance can be performed in a matter of minutes.

Despite these successes, we definitely ran into obstacles. The good thing about obstacles is that they give us a chance to develop. The bad thing is the cost that often comes with this experience—time and energy. So, if our experiences can work for you to save money, time, and energy, then I am more than happy to share!

Migration when it works
We define migration as restructuring and adjusting content according to common processes and standards. Most of our content is related to manuals for pumps and mixers. Since 3,000 pump and mixer manuals were migrated in 2008, and the number keeps growing, up to 90 percent of the content is already created and available in the CMS. Very few new topics need to be written when migrating additional manuals for pumps and mixers.
Through the migration, the writers work together with Subject Matter Experts (SMEs) to get correct data, procedures, and safety instructions in place. When the writers and SMEs are familiar with the routines and system, and are happy using them, this type of migration works smoothly without much assistance.

Whenever the routines or systems are not yet clearly stated or understood by a writer, SME, or manager, we rename a “migration project” to an “integration project.” This typically happens in any of the following cases:
When Xylem acquires a new brand and set of products
When one of the brands agrees to take part in the standard documentation development process
When documentation project team members (managers, SMEs, and writers) have not yet used the Xylem TDG routines and standards or used it a very long time ago

For an integration project, we include agreements with managers about the time needed and the tasks required to complete a documentation project. For managers and SMEs to understand, we inform them about the benefits, the processes, and need for commitment. Training and coaching is critical for any new writer or SME or for those who have not used the routines or system for a long time. We need to prepare them for what will happen next, what they are expected to do, and how the new system will affect the result. We also need to capture any bump in the road that may hinder the workflow. We need to work with the writers and SMEs throughout their ongoing projects. The integration process looks roughly like the following:

Prepare the new organization for the change.
Prepare writers for the migration.
Create an Information Architecture team.
Create system/rule development teams.
Provide training and exercises prior to using the working environment.
Test the output production and the translation processes.
Complete the production plan.
Review and approve the production plan.
Develop the first draft content.
Perform quality reviews and updates.
Hold SME reviews.
Finalize and publish.

The Big Migration 2008
We learned a lot during the migration of pump and mixer manuals in 2008. Over 3,000 manuals in a great variety of formats, as well as look and feel, were transformed to reusable DITA topics in our repository and published as standard styled PDFs.

Vendor writers
We used two teams of vendor writers for the migration:
One team was based in USA
One team had writers in Sweden and Italy

These teams had already received training and experience from the pilot, where they had been part of the testing and evaluation of the processes, system, and rule set. We had followed their work thoroughly:
Reviewing their topics
Acting as communication links between the writers and the SMEs
Evaluating any identified need for adjustments and then taking action where improvement was needed

For the migration, each vendor team designated one person to perform topic quality reviews and train writers where needed.

Internal Value Center Contacts
After this first migration project, internal Value Center Contacts (VCCs) took over the maintenance of the migrated contents. The VCCs were designated people working locally at technical documentation departments and marketing departments at different sites. The VCCs would learn from our courses and by following the vendor writers’ work. All VCCs had close contact with the SMEs on site. They acted as communication links between the writers and the SMEs, performed important parts of the task analysis, and pushed the process forward until they had published and sent the outputs for translation. We kicked off the analysis of reuse across product lines and coached them in running meetings, asking questions of SMEs, and communicating any need for assistance in completing their documentation projects.
The process
In 2009, the documentation process resembled Figure 1.

SMEs needs and reactions
I had the privilege of following most of the projects through the migration in 2009, in different activities, such as
Meetings with the writers and VCCs twice a week
Weekly project overhaul with the vendor project managers
E-mail correspondence and telephone calls

As a result, I could identify where in the loop of a project the pitfalls normally occurred and learn about possible reasons why. Table 1 shows the top four pitfalls in ranked order.
The most common challenge was that a documentation project would start later than originally planned, often because SMEs were occupied with product development. We reworked manuals of products that had been released ages ago, and our engineers’ first job is to develop new products. The documentation project couldn’t cover the cost of vendor writers put on hold, and we were tasked to deliver by the end of the year. Our Leadership Team made a great effort to resolve the urgent situation with Senior Management, and we made up new plans with the local Engineering Managers to verify their support.
Several things would happen along the way, as migration projects started later than expected or were paused for a peak in product development cycles. SMEs occupied with product design in their daily work forgot about the end-user perspective that we had taught them and followed when designing manuals. Where a time gap or switch of SMEs occurred, we needed to schedule time with them for additional training sessions. If we missed this training, the SMEs did not know what was expected from them in the process. Here are some examples of what we learned:
In topic annotations, we received comments from some SMEs saying things that did not help us correct the content, for example: “Really!!!” These comments made us aware of their need for training in how to comment.
Some SMEs were shocked when reviewing the PDFs for their first time. Although everyone had been informed and approved the change and the principles behind it, they had still expected a certain content structure, wording, and look and feel to be the same as before the migration. In their reviews, we would get comments such as:
Where’s the image on page 3?
Too much white space on the page!
The changes made unprepared SMEs fear that some of the important information from the legacy materials might have been lost or wrong. In some projects, we spent time logging in spreadsheets how chunks of information had been moved, restructured, and rewritten in order to win the SMEs’ trust that all information of value was in place.
Structured writing does not only make information easier to find, understand, and use; it also makes it clearer when something is wrong. Therefore, the review process and the need for further research for an update took more of the SMEs’ time than expected.

Lessons learned #1
Changes make people insecure; we must make sure they trust that we are in control of what we are doing. The lessons we learned from the migration in 2009 were as follows:
We must have very clear agreements in place, including time per SME, before we can kick off a migration project.
Training must be provided at the time of each action so that everyone knows exactly what to do right then and there.
We must prepare each and every SME for the change of content structure and the look and feel of the output several times before the review process.

As a result of our experiences, we moved our integration plan into a template spreadsheet with one tab for the agreements and one for the operational work, where each step required in an action was included together with a name and date. Now, we could use this template with the documentation project teams to communicate how each step depended on another and follow up on any delays in the process.
After the migration, we were also able to prepare the SMEs for the standard content structure and discuss any issue related to output style sheets well in advance of publication.

Value Center Contacts becoming corporate writers
In 2009, we established the corporate ITT Shared Service team. Six persons located in Sweden, India, and the US maintained the documentation system and authoring standards and trained and supported writers from the different companies.
At that time, the VCCs started taking responsibility for technical writing. All VCCs worked for local managers who had local priorities. Their positions could change quickly, and we lost many of them through changes in the organization. We wanted to maintain competence, and our strategy was to make sure we all worked under the same management. Therefore, the corporate Shared Services team and the technical writers in Sweden built the Xylem TDG. Today, two technical writers are still employed by a local company and are working in our system, but they have limited access to the repository.
Initially, all of the writers that we trained handled desktop publishing in different formats in parallel with the documentation in our system. The workload they had was already heavy, and, on top of that, they were now forced to learn a new system and new ways of thinking! The writers in Sweden had the advantage of having the vendor writers physically close; the others used e-mail, telephone, and web meetings for the knowledge transition. In any case, this change process was a great challenge. We had counted on the need for knowledge transfer, but lacked experience in dealing with people’s anger, fear, and resistance. We had focused so much on the information end users, SMEs, and stakeholders that we missed the fact that technical writers are as insecure with changes as others.
We needed the new writer’s help to clearly understand how we could be part of the solution rather than part of the problem.
Lessons learned #2
We have learned that to change, you need to feel capable and remember that you have the capacity to grow. Therefore, training and reviewing technical writers to change their ways of working is better when we consult with them as experts in their area of interest. Letting go of the habit of training and informing and starting to ask the right questions was a step in the right direction. When someone worked in a way that was not in accordance with the common rules, we learned not only to remind them how they should work, but also discuss the possible reasons they were working in different ways. Table 2 shows an example of how behavior can guide the communication.
Our goal is a common roadmap, mutual trust, and collaboration. We learned that two-way communication is extremely important to capture everyone’s knowledge and areas of interest.
In the Xylem TDG today, most members have one or more expert roles and are part of the solution-oriented teams. These roles support the people running every documentation project. During integration of new projects, these skills are important when new requirements and questions need to be resolved.
The people running integration projects also have support through coaching or from management, depending on purpose and needs. The Integration Planning Template has been modified with columns for when and whom to support.

Table 3 shows an example of part of an integration plan, where agreements, information, training, and coaching are included as part of the process.
The template integration action plan assists everyone in remembering all agreements, actions, and training assignments that could possibly be needed in the integration project. If a step is excluded from the process, that decision is deliberately made; no step is accidentally forgotten. This template is used to clearly communicate in what order to perform each action, who will do it, when it will be completed, and what kind of support he or she needs to complete the action. The plan helps ensure that we get commitment from all to support an action, such as Action Number 7 in Table 3, before moving forward to Action 8. These few examples show how obstacles help us improve, ensuring that each person involved in the integration project will get the help needed to contribute to high quality content as effectively as possible.


Figure 6: Keywords in Bookmap in Author View

Figure 7 shows an example of a file opened in Author mode.


Figure 7: Author View in oXygen

6 Produce deliverable

The final step in this process is producing the deliverable. The deliverable is either completed by the information architect or someone on the Production team. In our case, we have a DITA-to-InCopy transform that we use to create an InCopy file that is then laid out in InDesign. After the InCopy files are generated, they are sent off to our layout specialists in Production. At this point, the process is the same as it was pre-DITA—the document is laid out and sent back to the DE for a final review before it is sent to be printed. I have used the out-of-the-box PDF transform to create an example of how the automatically generated content is displayed. Figure 8 is from a PDF of content shown in Figure 7.


Figure 8: PDF Output with Key Resolved

Deployment Challenges

The challenge in automating the syllabi update process was not with the technology or the content architecture; it was really a process and change management issue. KPE has different authors working independently on these syllabi, so there has historically been little to no agreement on what the standard content should actually be in a syllabus. To be fair, these authors have never previously had the opportunity to collaborate and agree on wording, which is a new challenge for them. If your organization has already tackled this issue, your transition to this kind of solution will be much easier than it has been for us here at KPE. That said, our DEs have taken the charge and are excited to do more work with DITA. When asked about the benefits of this solution, the DE said, “Being able to distinguish generic content from state-specific content in DITA was a plus. This allows DEs to see what is shared (generic) content from state-specific content which helps the DE address the change accordingly either by letting the author know that making this change will affect all states and cannot be made or if it is ok, make the change and it will be changed in all other syllabi. This then ensured we were being consistent with changes.” This process consistently improves the quality of our content by providing our students the same information regardless of where they live.

Next Steps

We are still working with our content specialists and development editors to determine the best possible template content, and as soon as that is locked down, we will begin rolling the DITA syllabus out to each state as it comes up for updates.

Other Uses

Although we developed this solution for product syllabi, there are certainly other potential uses. In particular, marketing material that has to have localized content (time zones, distributors, and so on) and business contracts are two other ways to use this method. If you are using DITA in this way or a similar method, I would love to hear from you to learn about how your group has approached similar challenges. CIDMIconNewsletter 

Peyton BentleyPeyton Bentley

Kaplan Professional Education

Peyton Bentley is an information architect at Kaplan Professional Education who has worked in printing and publishing for almost twenty years. As the first IA for Kaplan Professional Education, he has been involved with developing the roles and responsibilities of the IA position, creating a content model, and moving legacy content to DITA.

Amber SwopeAmber Swope

DITA Strategies, Inc.

Amber Swope is an internationally-recognized expert on the Darwin Information Typing Architecture (DITA) who specializes in helping companies design and deliver compelling customer experiences.