Skip to main content
October 24, 2022

The challenges of replatforming content (podcast)

In episode 130 of The Content Strategy Experts podcast, Bill Swallow and Sarah O’Keefe talk about the challenges of replatforming content from one system to another.

Links are always a problem, especially cross-document links. Reusable content tends to be handled differently in different systems, or almost the same, but not quite, which is almost worse.

—Sarah O’Keefe

Bill Swallow:                     Welcome to the Content Strategy Experts Podcast, brought to you by Scriptorium. Since 1997, Scriptorium has helped companies manage, structure, organize and distribute content in an efficient way. In this episode, we talk about replatforming: the process of moving content from one system to another. Hi, I’m Bill Swallow.

Sarah O’Keefe:                 And I’m Sarah O’Keefe.

BS:                                      And I guess the best place to start here, Sarah: what is replatforming?

SO:                                     My definition of replatforming is that it is when you decide to move your content assets from one system to another. You may or may not change the file format, but when we talk about replatforming, the focus is on the idea that both systems support the same format, whether it’s DITA or HTML or anything else, and we’re changing the authoring and the publishing systems. So we are changing the platform that the content resides on, but not necessarily the content itself.

BS:                                      Okay. So, given that the content’s not changing, it’s a pretty straightforward process, right?

SO:                                     Sure. It’s great.

BS:                                      I’ll start with a loaded question,

SO:                                     Right. It is easier than the alternative. So if we’re comparing replatforming to something like taking completely unstructured, ad-hoc-formatted Word files or InDesign files and moving them over into structured content in some rigorous approach for the very first time ever, then yes, replatforming is easy. But with that said, you still run into some really annoying and costly complications when you do replatform.

BS:                                      What types of things?

SO:                                     Well, the usual suspects, right? Links are always a problem, especially cross-document links. Reusable content tends to be handled differently in different systems, or almost the same, but not quite, which is almost worse. Variables, conditionals, metadata…

So for example, if you take metadata, if you have your existing structured content in some sort of a component content management system, a CCMS, then there are at least two different places where you can store your metadata. There are probably more, but we’ll start with two. And the two typically are inside your content at the element level, so maybe a paragraph or a section or a topic; you could apply metadata to that element, to that paragraph element or section element or something like that. Also, in most CCMS, you can apply metadata at the CCMS level so the CCMS itself has a way to manage, govern, and apply metadata at the CCMS object level.

Now, the object level in the CCMS could be a lot of things. We maybe could assume it’s a topic, but if you’re talking about a reusable object, it might just be a little paragraph or it could be a variable, et cetera. And what you run into is that your old system, your legacy system where all your content currently is, has a certain way that is optimal to apply metadata and to manage metadata. And your new System B also has an optimal way of doing things, and the two are not exactly identical. Oh, and there’s a non-zero possibility that when you implemented System A eight or ten years ago, you maybe did some things that weren’t optimal.

So your metadata is stashed using a certain approach. Well, actually we hope there’s a certain approach and a certain system, because of course, option C is that it’s all over the place. But even if you did everything exactly right in the old system, there’s a decent chance that in the new system you’re going to have to make some changes.

BS:                                      Right, and mapping metadata from one system to the other, they may not even handle the same types of metadata fields that System A had versus what you need in System B. So you may end up having to either create a lot of metadata in System B from scratch, or have to somehow port the metadata over and make it fit where it may not be optimal to use, which I would not recommend. But there’s some degree of legacy carryover that you need to maintain when you’re switching these systems.

SO:                                     And I think it’s worth noting that the baseline metadata: who is the author? When was it last updated? All the administrative stuff. That will carry over well enough. The problems you’re going to run into have to do with places where you’ve done customized metadata, which almost certainly is the metadata that has the most business value for you.

BS:                                      Right, right. Even things like profiling metadata may be handled completely differently in a new system.

SO:                                     Yeah, I mean, in theory it’s DITA, and so it should just carry over, but, well, here we are.

BS:                                      So given some of these gotchas, what are some of the best practices that you recommend for replatforming?

SO:                                     Well, of course you should plan. Plan the project and don’t just jump in. At the same time, and in total contradiction to “you should plan”, it’s also worth trying it, doing a little proof of concept, pulling some files over just to see what happens. But expect that things will go sideways, and then you’ll need to plan some more to figure out how you’re going to do this.

BS:                                      Right. And there’s a difference between the various different types of assets that you might be moving over. So you might have some content files that might be different, some different types of content files that would be handled differently. And then you have other things like images, videos and so forth that may have a completely different approach to being stored and managed.

SO:                                     Right. So definitely figure out what’s going to change, and what does it look like to move this stuff over, and how are you going to do it? In many cases, our clients are taking a replatforming as an opportunity to also do content-modeling updates. So let’s say that 10 years ago you put in place a system based on DITA 1.0, and now you’re moving into something new and at this point you look at, well, we could move it up to DITA 1.3, take advantages of keys and some other fun things that we can do in that system. I do think it’s useful to separate the replatforming, the systems work, from the content-modeling updates. The content-modeling updates, in theory, you could do in the old system, assuming it supports the latest and greatest, but there’s value in doing the content modeling, even if you’re not replatforming. And the challenges you have in replatforming are different from the challenges you have in doing content-modeling, information-architecture updates.

BS:                                      When we’re replatforming, it really is an ideal time to do that level of content modeling and restructuring. Okay. So aside from setting up your project and planning properly, giving it a few test goes and taking the opportunity for content modeling, are there any other recommendations for replatforming?

SO:                                     I would look for places where you can get wins, especially if they’re easy wins. Find the things about the current system… Or sorry, you don’t need to find them. Put out a message to the team that works in the current system, and ask them what annoys them about the current system.

BS:                                      Oh, boy.

SO:                                     Yeah. And then after the deluge, read through them all and figure out whether and how you can address those issues. Can you make the new system better? Can you improve on the things that are in the old system that are just long-standing annoyances that people are unhappy about and fix them? Because if you can go through and fix that stuff and get some wins for your team on the new system, that’s going to go a long way to helping to make the transition go smoothly. People are going to be much happier about switching systems if there’s a win: “I’ve always been super annoyed by how this particular thing works or doesn’t work, and oh, it is so much better in the new system.”

BS:                                      And it’s not just the authors in that case. There are a lot of other groups and people who are using the system in one way or another.

SO:                                     And there may be new groups. It’s common, for example, that old systems people are still doing review outside the CCMS: PDF-based, email-based review, that kind of thing. Most of the new systems, you’re going to be doing reviews in some sort of a review workflow that is built in. So there’s a big transition there, and you may be talking about bringing in dozens or hundreds of new review users that were not there previously.

BS:                                      So there’s likely also a good deal of planning for not just change management among those who are using the system for authoring and managing content, but a wider scope as well.

SO:                                     Right, exactly. And this is maybe the most critical one. One of the biggest… Sorry, folks. I’m going to say mistakes. One of the biggest mistakes that we’re seeing in making these transitions is what we call the burning platform problem. So this is jargon for, “I have to get off of Platform X because it’s burning.”

Now, software typically does not burn. So what we mean here is: my software, the contract expires December 31st. If we’re not off it by December 31st, we have to pay maintenance for another year or another quarter, or the software is going into some sort of end-of-life status. It is rare that you reach the point where the software is actually being turned off, in the sense of on December 31st, this particular vendor will cease to exist and our software will cease to work. That’s not usually the case, but we have seen numerous, numerous projects where clients are telling us, “I need you to finish this by December 31st, because that’s when our maintenance contract expires.”

That is a cart-before-the-horse approach, and of course, these conversations are always happening on September 17th. “We have to get this done by December 31st.” “Well, but it’s a six month project.” And they’re like, “I don’t care. Make it happen.” Well, no, we can’t, and neither can you as the customer. And when the project is driven by an external deadline that really doesn’t have anything to do with the actual project… We have a project that’s going to take six months and you’re telling me to do it in two and a half, or three and a half.

Well, that’s going to increase cost. It’s going to increase risk. There are going to be mistakes. There are going to be problems where somebody who needs to sign off on something is out on PTO or vacation or maternity leave or a trip around the world, or they’re at an onsite and can’t be reached. And so there’s delay. And what we’re doing is we’re putting pressure on the project in order to meet an artificial deadline that is not really critical.

And so I think that it makes a lot more sense to plan ahead, pay the maintenance for an extra quarter or maybe even an extra year, and get it right. You may end up running in parallel for a bit, running both the old system and the new system so that you can validate that everything’s working and we didn’t miss any edge cases and that type of thing. But going live on a system that isn’t ready because of some, I’m going to say artificially imposed deadline that did not allow for a proper project cadence is risky.

BS:                                      It asks for trouble. Exactly. So not only is it risky to have a ticking time-bomb on your legacy system, but it also invites opportunities to not exactly implement things the way that you ideally should in the new system. So we could probably talk for hours on this bit of squeeze-time, but I think this is probably a good place to wrap this episode up. Sarah, thank you very much.

SO:                                     Thank you.

BS:                                      And thank you for listening to the Content Strategy Experts Podcast, brought to you by Scriptorium. For more information, visit or check the show notes for relevant links.