Planning a re-platforming project

Often, re-platforming projects come as part of a website re-design, and the question soon arises: what to do with the existing content?

It might be tempting to write a script to "lift and shift" content from its current origin and give it a new home in the Content Lake with the same structure it had before. Chances are that the CMS you are moving from has locked your content down to "posts" and "pages" and is stored as HTML with presentation-specific code tailored for a design you're trying to get out of.

You might also be under pressure to deliver on a tight deadline and maybe with fewer resources than you would prefer. Of course, it’s natural to look for shortcuts! But let’s be circumspect about which of them to take.

Re-platforming projects often get approved when people in an organization feel the pain and constraints of their current systems. However, stakeholders may not always recognize that a lack of well-structured content and a cohesive content operation strategy create business challenges that hinder productivity and innovation. Simply changing technology without addressing these underlying issues may not lead to significant improvements.

To truly benefit from a re-platforming initiative, organizations should take a holistic approach encompassing the technical aspects, content operations, and the content itself. This involves:

1. Auditing and restructuring existing content to ensure it is well-organized, consistent, and optimized for the new platform.
2. Developing a content strategy that aligns with business goals, user needs, and the capabilities of the new technology.
3. Establishing a content governance framework to maintain quality, consistency, and efficiency across the content lifecycle.
4. Training and empowering content creators and managers to get the most out of the new platform and adhere to best practices effectively.

This might seem like a lot, but you can always start doing some and allow for iteration as you learn and experience more. There are different ways of scoping each of these, and in many cases, it’s about building habits in your team and organizations – which you do one step at a time.

Recreating your content structure as-is in a new environment opens the door to recreating your existing problems, just on a new stack.

Before initiating the content migration part of the re-platforming project, alternative content models may be beneficial. Could your organization benefit from modifying content that will live in Sanity into different shapes? With different connected references?

For example, in a default WordPress install, you have just "Posts" and "Pages." Most mature WordPress installations will also have a set of custom types for Pages and Posts.

Many WordPress users use Pages for almost everything and templates as differentiators. A "person" profile might be a "page using the person template." Thus, content is bound by a specific presentation and hierarchy on the website, which stifles reuse and makes it hard or impossible to bring into other channels.

With Sanity, you model entities for what they are, not what they look like on the website. So when migrating, perhaps you split "pages" of content into different document types instead of just importing everything as-is and repeating the same mistakes of the past.

New technology may require new skill requirements for your team. If you're coming from a monolith running on PHP, your developer team may need to up-skill with JavaScript to configure the Studio. (Sanity does have a PHP client if you plan to keep your front end there!). Fortunately, developing with Sanity means using the same skills as creating a front end for the web. Developers will recognize many of the same conventions and mental models configuring and customizing the Studio as with the end-user experience.

While training is potentially required for developers, it is absolutely required for content creators. Especially when going from a presentation-first to a structured content platform. Don't just ship the finalized new stack and send over the new URL! The most successful re-platforming projects we have seen have taken careful steps to ensure content teams are involved along the journey.

In fact, a re-platforming project is best approached as a cross-disciplinary exercise.

Approaching the re-platforming as a team, including product owners, content creators, designers, and developers, helps ensure the success of the project.

Anticipate writing new documentation and creating new training materials for content. Keep track of your decisions and the problems they solve. For example, why have some content models changed, or why was the content re-platforming performed at all? This way, latecomers to the project can be brought up to speed quickly.

There is a chance that some content will actually prefer the legacy platform, mainly because it is familiar—even if it is slow or broken. A re-platforming upsets this familiarity. Your migration team's job is to smooth this transition through involvement, documentation, and education.

Prepare a feedback strategy so that as developers configure the new platform and migrate into it, authors can interact with preview builds of your Studio and provide feedback. No content model or configuration is perfect the first time. You'll likely find challenges you had not initially planned for at the start of the migration process. Iterate and improve.

The quality and availability of your existing CMS will determine your migration strategy.

You may be coming from a product with a content API like the WordPress REST API, allowing you to run migrations against up-to-date content. This has the massive benefit of not requiring a "content freeze" when you're finally ready to go live on Sanity.

Your existing platform may only allow you to export your existing data into local files, like XML, or require you to export content directly from a database. This can make continuous migrations more laborious as manual steps and coordination are involved.

Worst of all, your existing system may have no export tooling or database access. Thankfully, web scraping is a viable strategy for retrieving content. Depending on the quality of your existing website's structure, it may provide a stable and predictable method of retrieving rich text, block content, and metadata. However, some tooling may be required to perform the scraping.

Content entropy happens over time when a system lacks proper validation and allows for inconsistency. You have to plan how to deal with this. Expect broken links, references to media, images, and users that no longer exist, empty paragraphs, lines with whitespace, and mismatched encoding.

Look for content you might not have to move because it no longer serves your and your team's needs. Make a prioritized list of essential content based on its role in the end-user experience and popularity as recorded in website analytics, etc. Selectively choose, clean, and filter all content as it is migrated across.

Your migration scripts will need to be written to account for this. Any image fetch that fails needs to be handled. Any referenced documents will need to exist. Anticipate writing verification and error handling in your code.

In the next lesson, you'll get introduced to technical concepts and terminology that usually come with re-platforming projects and modernizing technology stacks.