Part 2: A Guide to Migrating to Structured Content

The decision to migrate from an unstructured to a structured content model isn’t one you should take lightly. There are many things to consider, including whether or not you need a component content management system (CCMS). We’ve created this two-part series to help you make the best decision for your company.

In part one, we explored the benefits of migrating to structured content for technical documentation, including improved scalability, reduced costs, and faster publishing cycles. We discussed how to evaluate your need for a CCMS and provided a step-by-step guide for deciding whether migration is right for your organization. 

After analyzing and assessing your requirements, you’ve decided that migrating to structured content makes good business sense. You also decided you will need a CCMS to manage your structured content. 

Now comes the real work: deciding what content to migrate, identifying opportunities for content reuse, and selecting the best CCMS to support your needs. Sarah O’Keefe, CEO and founder of Scriptorium, and Paligo Solutions Engineer and Information Architect Gershon Joseph have plenty of great advice to help you.

And that leads us to part 2, so let’s dive in.

The decision to migrate is a business decision. Some customers want to import all their content into the new CCMS, but the more you choose to import, the more time and effort it will cost (and possibly the costs of a third party to do the work for you). So, you have some decisions to make.

First, a CCMS isn’t a digital asset management system (DAM). It’s more than just a place to store all your content. There is no reason to migrate every piece of content you have if you don’t need to. 

Gershon suggests that if you can afford to start fresh and take advantage of the new paradigm, you should. Some customers create a clean content set in the CCMS with a new, well-thought-out content strategy and information architecture.

An alternative is to migrate a minimum viable set of content. For example, if you have five product variants that share a lot of the same content, import one of those variants and reconfigure it with variables, profiling, etc, so you can reuse it. Once you have a variant in the CCMS, extend it to create the other variants. This process is less work than bringing all the variants over and reconfiguring the content for reuse.

The amount of effort your migration project will take also depends on how clean your unstructured content is to start with. Migration should be quick and relatively easy if styles are applied consistently and correctly over 100% of the content set. 

This is NEVER the case.

Gershon said that often, a customer thinks its content is well governed, but this isn’t always the case. For example, each writer may have a different approach to formatting. This is especially true with startups or companies whose early content is not typically written by a technical writer. When writing in MS Word or Google Docs, many writers apply local formatting or are inconsistent in their style choices. 

Even if you have a template with defined styles, it’s not unusual for a writer to modify them slightly to support the content they are writing. 

To import content, you have to match the formatting styles to XML constructs. This means that you will need to fix the Word files so the content formatting is consistent before you migrate it. If you don’t, the import won’t work properly. 

How well has the template in the backend been formatted? Do you have styles in Word, FrameMaker, or InDesign?

Sarah O’Keefe said Framemaker content will be a bit cleaner because it leverages templates and tags. Word is a mixed bag, and InDesign is an absolute trainwreck. InDesign is a tool for creating nice-looking PDFs, so you design the page to look good, which is completely incompatible with consistent tags and styles.

Look at your unstructured content. As you start to move it to a structured format, you’ll quickly expose the tricks and workarounds that writers have performed because you are removing the formatting, 

So, what really happens is that when you look at your unstructured content, all the little tricks and workarounds and things that you got away with in unstructured content are going to be exposed when you move over to a structured authoring environment because you’re separating off the formatting. So all those things you did for formatting purposes are now irrelevant, and they go away. And so what’s left is that corpus of content. – Sarah O’Keefe

Sarah said there are workarounds to this challenge with custom scripting, such as local overrides (e.g., it looks like an H1, but it’s marked as a body tag), but custom scripting costs money.

If you’re not going to migrate all your content to the CCMS, how do you decide what content to migrate? Sarah explains a few ways you can go.

First, triage your content (as Gershon said above) and select the core content you need on a regular basis. Do you have to bring in fifty thousand pages of content, or can you reduce that to five or ten thousand pages of core content?

Alternatively, take a just-in-time (JIT) approach and only move in content as you need it. For example, if the content is in maintenance mode—meaning it’s completed and published, and you only need to change it every two years—leave it where it is, Sarah said.

For all the live content you need to move over, consider starting with content you need to work on in the next six months—a subset within a subset. 

As you work out the conversion process and understand the front-end cleanup that needs to happen, you can put the content into a sequence that migrates it over as needed. Sarah said this doesn’t always work, but it’s worth trying for some. 

A note on translations: If your content is translated, you must also think about what needs to change with your translation process. Translation memory in your Translation Management System must be realigned to ensure the legacy translation memory is fully leveraged when you start translating content within the CCMS.

The most important thing to remember is that no matter how clean your content is for migration, there will always be post-cleanup on the CCMS side. 

Spend time on the pre-work, it absolutely has to be done. But don’t forget there will also be post-import cleanup or rework on the other side. 

You’re never going to get a perfect migration. There’s no such thing. There’s always work to be done upfront and work to be done afterward, and that needs to be considered as part of that migration effort planning. – Gershon Joseph

Sarah O’Keefe said that as you move from unstructured content to structured content, you also need to consider the context of how that content is being produced.

For example, if you were creating PDF documents, you were concerned with creating chapters and ensuring the page layout was right, tweaking the layout to keep lists together, or keeping an image with specific text. 

When your content is in a CCMS, you are thinking more about HTML, including HTML for a website, knowledge base, or customer portal. You could still also be creating PDFs. Creating content for multiple channels requires a new approach to design and a new process for creating and structuring your content. 

You also need to think about writing for search engines, including metadata, taxonomy, synonyms, and relevancy. 

So it’s a whole different paradigm and a different concept. You can’t just write as if you’re still writing for PDF and pages. You need to write something more generic now. And actually, I would propose you don’t even write specifically for the online.  – Gershon Joseph

Gershon recommends that you write generically—not for PDF but also not specifically for online. Instead, write for topics. A topic contains a single idea, which means you can easily repurpose (reuse) that content in the CCMS for multiple publications, channels, and other teams, such as instructional content for learning management or feature descriptions for the marketing website. 

Write so it works regardless of context or output. – Gershon Joseph

The question you may have at this point is, how do you identify content that is reusable? Glad you asked.

One of the things you should be thinking about as you plan your migration process is identifying what content you can reuse. 

When you create unstructured content, you aren’t thinking about reuse. You write the content as you need. Sure, you might copy and paste content from another document initially to speed up the writing process, but it’s unlikely (and almost impossible) to keep that pasted content in sync. What you wind up with is multiple versions of some content. 

So, what are some ways to identify where content reuse can happen?

Sarah suggests looking at all your versions of a piece of content and selecting the best one. You can also rewrite the content so it can be used in all versions, adding variants where necessary.

This is where best practices for technical writing become helpful. Spend some time understanding what they are and how to apply them. Remember, there is a cost associated with managing every piece of content – the less you have, the less overall costs you have. That said, Sarah is not suggesting you throw everything away and start from scratch. Take your time to find the best path forward.

When you find that one way you want to write a piece of content (topic), Gershon said to expand its usage with variables and profiling, enabling you to use the content in different contexts and publications. 

For example, the first few steps of any procedure are the same. Without reuse, each writer may write those steps differently, which can be confusing to end users. When writing for reuse, you would create those first steps as a separate procedure that can be reused within other procedures.  

Working with product variants is another example of reuse working well. Gershon provided the example of a piece of hardware with a back panel that has additional interfaces for certain models. When you create the manual for that product, you can employ profiling to ensure that people who work with the model with the additional interfaces get the version of the manual that explains how to use them. 

A more advanced example is when you provide white-label content for OEM products. In this example, the content is all the same, except the name of the product or feature is different. Profiling and variables also work well in this situation.

We’ve looked at the things you need to consider when planning your migration project, but it makes sense to stop for a minute and talk about the three biggest mistakes companies make so you can avoid them.

Too many companies decide to migrate all their legacy content as-is, thinking that once the content is in the CCMS, they will rework it later. 

It never happens. 

Once that content is migrated, there will always be something more important to do. Most technical documentation teams are small and are already overrun by work. Thinking there will be time to clean up the content, apply a proper structure and taxonomy, and work on new writing projects is wishful thinking. 

Take the time upfront to plan your migration properly.

It’s not. Some companies assume migration happens ‘auto-magically’ and plan for little time and effort.

Depending on how much content you have, the condition of it, and what you decide to migrate to the CCMS, the migration process will have different levels of complexity. You have to take the time to understand what’s involved in the migration process to determine the best path forward. Remember what Gershon said, “You’re never going to get a perfect migration. There’s no such thing. There’s always work to be done upfront and work to be done afterward, and that needs to be considered as part of that migration effort planning.” 

The CCMS vendor you select will have a migration process that includes technology. However relying solely on their process will not result in a successful migration if you don’t do any content strategy or information architecture beforehand.

Once your content is migrated, you want to hit the ground running. That means leveraging the CCMS’s capabilities from the start, such as structure, taxonomy, versioning, workflow, and collaboration. 

If you plan your content properly from the beginning, you can use these capabilities effectively because the system will be set up correctly.

Much of what we’ve discussed assumes you are migrating to a CCMS to take advantage of structured content. Of course, that means you need to select a CCMS to use. In part one, we discussed why you would need a CCMS. At this point, we’re assuming you need one and have already performed a high-level look at your options.

The most important thing to remember is that all CCMS are not the same. Sure, there are many similar features, but how those features work often differs, as does the amount of effort required by your technical documentation managers and writers to use them.

You’ve documented your requirements, so now is the time to evaluate how each CCMS supports them. The best way to do this is to create a spreadsheet that lists your requirements and then map how each CCMS supports them. 

There are several key features or capabilities to look at, including:

1. How structured authoring is set up and content reuse is applied.
2. How external team members can collaborate on content creation or review and approval.
3. How versioning works.
4. How easy (or hard) it is to create profiles or variants to use in content.
5. How translations work (if you have a global customer base).
6. How the CCMS supports publishing – what the options are and how you set up publications.
7. If the CCMS integrates with your key systems. 

In addition, you’ll need to understand how the CCMS licensing works, such as the licenses for authors and reviewers, the number of languages supported, and the amount of storage included.

When you narrow down your options, request a custom demo and run a pilot for the best one before you make the final decision.

There are several great resources on the Paligo blog that can help you. Here are just a few:

• Fundamentals of Documentation Management with a CCMS
• Producing Technical Communication Faster With a CCMS
• Streamline Content Operations with Content-as-a-Service and a CCMS
• Unlock the Power of Content Reuse in Your Technical Documentation

We hope this extensive guide on migrating to a structured content model and a CCMS is helpful. We’ll leave you with a few important tips. 

First, the better the up-front planning, the easier the migration will be, and the better the end results. Second, plan for your target state before you migrate to properly plan how your documentation team will work once the migration is complete.

Also, if you have a large content set, are a medium or large enterprise, or lack information architecture skills (including structured content and content reuse), consider hiring an external consultant to help you plan and execute your migration successfully. 

Finally, bring your team along with you. Don’t do all the work, and expect your documentation team to start using the CCMS. Involve them in the process from the beginning, from identifying the content to migrate to mapping out the structured content model to selecting and implementing a CCMS. And don’t forget training. Much of this will be new to your writers, editors, and SMEs, so build a training plan that helps them hit the ground running once the CCMS is set up and your content is migrated.