Fall 2024

Configured, converted, and migrated, oh my!

Sarah Rowe and Bobbi Werner, Baxter

Introduction

We recently transitioned to a new CCMS. We are writing about our journey from the perspective of the CCMS administrator and the manager based on our third ConVEx presentation about this transition.

Balancing priorities

Adding an overhead project on top of the regular workload means balancing priorities and resources. We defined a core team primarily responsible for vetting candidate systems and laying the groundwork for administering a new system. Part of this process involved specialized training for the core team, which we would later complement with training for the whole team in DITA authoring and how to use the new system. We had to anticipate and accommodate key project milestones the Tech Comm team supported. Could we avoid a writing freeze? What was our backup plan if we encountered delays?

A key date for us was the scheduled exit from the initial system…when our current subscription expired. Could we schedule overlap between the systems? If not, what would that mean for the timing of translations and release of our product literature?

Questions that we had to answer included the following:

How ambitious could we be when it came to special features and customizations that would make our output so much more reusable and consistent?
What could we build into a system that would support a more positive user experience on our team?
What systems would support an even more forward-looking vision for user content?
To what extent would our approved budget constrain us or allow us to dream on a grander scale?

Progress

Since last year, we have accomplished several key tasks and milestones:

✓ Finalized plans and selected a new system – If you attended our presentation last year or read our follow-up newsletter article, you know we were on the verge of a decision.

✓ Continue to work through internal transition and integration with our new parent company.

✓ Established a baseline of business metrics and KPIs to assess system performance and document value to the business.

✓ Wrote new plugins and transforms with a consultant.

✓ Set up the new system with the tool vendor and completed UAT.

✓ Converted and migrated selected content with a consultant, and we also completed substantial cleanup of those files.

✓ Deepened core team (admin) skills and launched user training (both admin and writer/illustrator). For illustrators on the team, this was an entirely new experience since they never had any contact with or exposure to our initial system.

The biggest news, of course, is that we opened shop! We experienced Go Live in our new system in February, just before we retired our old system.

Once we were in the system, we introduced team members to the system strategically:

Focused first on a Lead Writer who had a pressing deadline. Our core team worked closely with him to model the work he would have to do.
The second group was writers experienced in our previous CCMS who had impending deadlines.
Next were the illustrators, who needed instruction in how to upload and save their artwork to the system.
Finally, we introduced the rest of the team to the system.

New team members will be onboarded based on workload, assignments to update content in the system, and previous experience.

Using real-life scenarios to get familiar with the system is very helpful.

Content samples

Whether you are migrating from one DITA tool to another or are implementing your first CCMS, you can get started anytime by prepping sample content. This sample content is necessary to try out system configuration options. We recommend having multiple versions of the same content with redlines of the changes between versions. Using real-life scenarios to get familiar with the system is very helpful. You will likely add the content multiple times while testing, so it is also helpful to identify a small subset of that sample content. You might import some of it and type in some of it.

Be sure to include content that represents a wide variety and that matches your content structure. You might have manuals that use bookmaps and chapter maps, quick references, or other custom types. Include all topic types that you plan to use. For us, that’s concept, reference, task, and troubleshooting. Troubleshooting topics are new to us because we were using an old DITA version that lacked that option, so we had to learn how to use this topic type. Also consider front matter, back matter, and appendices. You might use lists (ordered and unordered), tables, figures, or diagrams. Include images of different sizes, formats, types (such as line art and screenshots).

If you translate, you’ll also need to have either the real translations or the ability to get them. We used a combination of “fake” translations by acting as the translator. We edited the xml files to either append the language name in the topic and map titles to make it clear that it was a different language, and sometimes we used a free xml parser tool to connect to free online translations. Be aware of your company policies if you use free online translations for testing. We didn’t need certified translations for system testing, so this worked out well for us.

Content categorization

Content categorization is about getting organized, the big picture, and it was surprisingly difficult. The old system had a flat structure for content, and we moved into a system with an organized structure. We spent a lot of time thinking about this, guesstimating how we would reuse content (because the reuse analysis was happening in parallel) and talking with folks internally, with our consultants, and with our tool vendor experts. We also looked at company product portfolios, and we considered both our current in-system content and content that would be moved into this system in the future. We used an e-whiteboard to lay out options and then used the whiteboard as a reference for those conversations. In the end, we circled back around to an initial concept! Despite coming full circle to where we started, it was still good to go through lots of options to gain confidence that we were making the best decision.

We established global libraries for things like symbols and common terms. Having an in-system trademark term library was accomplished with a lot of leg work, and it is already paying off for us. While content categorization doesn’t directly impact our customers, it does have a big impact on how we use the system internally and how we reuse content. Indirectly, more consistency is ultimately better for our customers. The overall organization of our content impacts system governance because it allows us to give the right access to the right people at the right time.

Content conversion

Why convert?

You might wonder why we didn’t just move all of our content into the new system and deal with it as we go. This was impractical because we had a gap of too many years without updates. Now we have a new DITA version, new DITA OT version, current best practices, and new company policies. We didn’t want to take our old problems with us. And we didn’t want to take outdated content with us that we weren’t going to use.

Who will convert?

For us, the answer was easy. The experts! There was no question about it. This was beyond the scope of what we would do in-house. In the future, we will reassess and balance resources for converting other content.

When to convert?

This should be done as close to implementation as possible so there is a short gap, less cleanup, and less downtime. More on this later.

What to convert?

This relates to the WHY question, as well as the need to balance time and money. We took care not to clutter up new system but also not leave too much behind. Our strategy involved prioritizing what we needed in the short-term and determining how to manage lower-priority content.

We identified content that we would archive in network storage just in case, but not spend time and money converting it because we were fairly certain that we wouldn’t need it.

Another complication of our old system’s flat structure and lack of organization was that we didn’t use workflows. This made it a pretty big job to know the status of each document–what was done, in progress, or even abandoned.

How to convert?

We used the experts. Our job was to decide what to convert, get files out of the old system, and provide the files to the experts. They worked their magic and then imported the converted content into our system. If you have the time, tools, and skills, you can do this work yourself, but this was not our situation.

Content migration

First of all, our CCMS is not our single source of truth. We use a separate system for approvals and delivery, and we don’t deliver directly to a customer portal. This is important to understand because it allows for having content in the system that isn’t the final content.

We had a cut-off date for sending files to be converted. Conversion takes time to analyze, make decisions, complete the conversion, and import. In the meantime, our project work continued in the old system to meet project deadlines.

That left us with a gap. How did we catch up on the deltas from the work in the old system versus what was converted and imported into the new system? We balanced resource allocations (time and money) for conversion. During the conversion process and review, we updated some of the source files. In most cases, we are now manually editing in the new system to catch up on the deltas.

This post-migration cleanup includes updating the content deltas and also resolving issues that couldn’t be automated during the conversion. Because of our compressed timeframe and inconsistencies in how we used the old system, we missed a number of details. Automation can’t fix everything, and some situations were unique and needed some tweaks. For example, inconsistent ways of tagging trademarked terms made some manual clean-up necessary.

System configuration

System configuration sometimes feel like it is never 100% “done,” but reviewing our project schedule every week confirmed how much we had actually accomplished.

The definition of “done” doesn’t mean perfect. We’ve circled back to adjust as needed, and we will continue to do so.

User permissions

If you’ve never used a centralized system, establishing user permissions will take some time to work through. Even if you have—like us—new features and options can change the plan and create new opportunities. Governance is good, but it also comes with lots of decision-making up front. Who should have an account is an easy question to answer. What roles should be set up, and some with higher-level privileges, is more difficult because it might be very different from what you do now.

Templates

Are you using templates now for topics and maps? Do you want to make any changes? We had a very different method for content creation in our old system. Useful templates are a welcome change for us. We also were able to include instructions within the templates that don’t get published as an aid to our users.

Content structure

This goes back to content categorization. Sarah tried many different options in the system, and at one point when she had to give a status update, she said, “I know what we DON’T want do to.” She had tried and rejected multiple options for various reasons! Finding the right path forward for us was process of elimination.

User acceptance testing

We had a list early in our planning phase of what features we wanted and didn’t want, but we needed to learn the system before writing our test scripts. This took a long time, but it was well worth it in the end. We had hundreds of testing scripts that encompassed every user role. We documented both our expected results and actual results and, when needed, asked more questions and made adjustments. We plan to review, update, and reuse the testing scripts over time as we make configuration changes and update the system.

Workflows

Workflows are another new addition for us. The system came with default workflows, and we relied heavily on the tool vendor’s experts for their recommendations based on our conversations about how we work and how we want to work in the future. We listened to possibilities and suggestions. This relieves the pain point of not knowing the status of our content.

Processes

Our processes also needed to be overhauled. The scope of this rework was huge, addressing how a writer starts a project, to our illustrators’ management of graphics, to translations, and everything in between. Every process needed to be reviewed, rewritten, and re-learned.

Output plugins

Our output plugins also required an overhaul. Output plugins control the look and feel of publications. They are what makes the content look pretty. Because of our lack of incremental updates over the years, we started from scratch with our output plugins. We relied on the experts to write our plugins, and they are teaching us how to maintain them. We reserve the option of going back to these experts for larger scope updates, but our goal is to be independent. Items that you can prep for ahead of time to either overhaul or create your first output plugins are gathering company logos, colors, fonts, font sizes, front cover design, and so much more. Gather good examples of the different delivery types that you have. This is especially challenging for us because we are straddling rebranding efforts and have multiple publishing scenarios to account for.

Next steps

Communicate with stakeholders

Communicating with stakeholders is critical even after Go Live. Transitions like this require their support to ensure ongoing justification for the system and the benefits it provides.

One example concerns the volume of post-conversion cleanup we’ve had to do which, combined with some delays during testing and a variety of other factors, meant that delays on project deliverables were likely to happen. We provided the sponsor of our project with analysis of the work we had in front of us to update content that was converted months ago but continued to be developed in our old system. He took that data and advised the project managers of impacts to schedule and instructed them to allow us the time we needed to ensure quality deliverables. His support included acknowledgment that the transition required additional time and the business should allow for that investment of time.

Implement a sustainability plan to promote success

The success of a CCMS implementation requires careful planning for the future. The following action plans will ensure the success and sustainability of the system:

Grow the team to ensure adequate staff, redundancy in key roles, and training to provide key skill sets and expertise.
Reassess and refine reuse libraries as we add more product portfolios to the system which add new features and terminology.
Review and update our Information Model (always in draft mode) to ensure it provides the team with clear direction; ensure the structure of content still makes sense and the Information Model aligns with it.

Promote the system

Implementing a CCMS is a considerable corporate investment, and our goal is to scale it across the business. Toward that end we plan to share demos with various groups and teams to showcase the system and its benefits. We also plan to secure additional seats in the system to encourage pilots/trials.

Future steps

Once we get our footing in the new system, we will pursue a series of activities to both enhance and extend the system. Our future plans include the following:

Convert non-DITA content and migrate it into new system. We still have lots of content across the company created with other tools. We have identified a couple of high-priority document sets that we will convert this summer/fall as pilot conversion projects.
Reduce reliance on other tools to author and publish content to take full advantage of all our new system has to offer.
Compare the metrics (looking at data both pre- and post-implementation). How are we tracking against our KPIs?
Establish and implement a collaborative review process in the system. This is something we’ve dreamed about for years, but soon it will be reality.
Scale the system to include other departments and/or business units and support their onboarding.
Conduct an annual review. Operate always with continuous improvement in mind.
- Review progress, challenges, opportunities, tech specs, overall structure of content.
- Make changes/pivot where necessary.
Maintain system with regular system upgrades

Lessons learned

A big lesson learned was the realities of the phases in our project. In our initial ConVEx presentation, we discussed this project as a linear process, as shown in an OASIS DITA adoption technical committee white paper. The white paper also describes how external influences might alter the project progression, and that’s what happened with us. We had overlap of project phases and lots of learning along the way!

While many of these lessons are specific to us and our circumstances, many also generalize and might apply to your situation:

DON’T go it alone – DO hire a consultant. This is something that we were convinced about three years ago, and then we were able to obtain the resources to do so.

DON’T use outdated methods – DO write an information model. Having the details in writing that the entire team has access to and can use as a reference makes it so much easier to be clear and consistent. This alleviates frustration and speeds up writing.

DON’T fail to communicate – DO use communication tools. When we first got started on our deployment project, communication was difficult. The email was overwhelming. Find a common tool that you can use with your core team internally and with your consultants and tool vendor.

DON’T give full permissions to everyone – DO plan system governance. Take the time to consider what roles you want to establish. You might not know who the right people are to fill those roles at first, but if you take the time to think it through and configure the roles, then it will be easy to test the system and to give the right permissions to the right people at the right time. You can also take away permissions as needed too!

DON’T overlook structure – DO take time to organize. As stated previously, content organization was a BIG deal for us. It might not be for you if you already have clarity. Our “I don’t know yet” status updates were responded to by the experts with a thumbs up “good for you for taking the time to think this through, because not enough people do, and they regret it later.”

DON’T assume clear expectations – DO keep asking questions. Even with all our questions, we had some situations where expectations were misunderstood, and we had to make time the in the project schedule to reassess.

DON’T expect to get everything – DO prepare to prioritize and reprioritize…many times! We had a soft deadline and a hard deadline. When we knew that we wouldn’t meet our soft deadline, we reprioritized every week (sometimes daily!).

DON’T lose sight of your goals – DO remember your mission. Don’t get so bogged down in the details that you forget about the big picture.

Conclusion

For us at Baxter, our mission is to save and sustain lives. Take time to get out of the weeds and remember your mission. Balancing the in-the-weeds time with the mission helps us to stay focused, to be flexible, and to adapt.

About the Authors:

Sarah Rowe has a passion for increasing efficiency with technology. She is a Senior Technical Writer at Baxter. Sarah manages the component content management system (CCMS) for Front Line Care medical device user documentation, coordinates translations, on-boards new users, and supports existing users. Sarah has an MS in Information Technology and is a member of CIDM and STC.

Bobbi Werner is Senior Manager, Technical Communication, at Baxter’s Front Line Care division. She leads a team of technical writers, illustrators, and specialists to create, update, and release user documentation for medical devices. Bobbi is a member of CIDM and STC. She is an STC Fellow and currently serves as Treasurer on the STC Executive Board.