The Migration Playbook That Actually Works

by Josh Oransky

Every EDS migration deck on the internet has the same five-phase diagram: discovery, content mapping, build, migration, launch. Every one of those phases hides about three weeks of real work that the deck doesn't mention. The playbook that actually works treats those hidden weeks as the project, and the phases as the project plan.

Phase zero: kill the wishlist

The first conversation in a migration is always the wishlist. The stakeholder team has had a year to think about everything they wanted to fix on the old site, and the migration feels like the moment to do it. It is not. The job of the migration is to land the existing site, faster and cleaner, on the new platform. Everything else is scope creep with a sympathetic narrative.

Spend the first week explicitly cutting the wishlist. Write a separate "post-launch backlog" document. Anything that isn't required for parity goes there. The stakeholder team will agree in the room and forget by next week. Circulate the wishlist-cut document widely, get it acknowledged by every senior sponsor, and refer back to it every time scope creep surfaces.

Phase one: content inventory the boring way

The inventory phase is the one teams want to skip. They have a sitemap. They have analytics. They think they know what's on the site. They are wrong.

Crawl the site. Get a row per URL with: page type, last-modified date, traffic last 90 days, inbound links, owner. Sort by traffic. The top 200 pages drive 95% of the value. The bottom thousand are stale and nobody is currently maintaining them.

This is where you find the brand-style page from 2018 that the legal team forgot existed and is still serving the wrong copy. This is where you find the campaign landing pages from a launch nobody currently working at the company remembers. The inventory is half the project.

Phase two: model the content, not the page

Resist the temptation to migrate page-by-page. The old site has visual variants of the same logical content type all over it. The new site needs one block per type, not one block per page. Model the content first, validate with the author team, then map old pages into the new model.

This is where the savings are. Five visual variants of a "feature card" on the old site become one block with a variant modifier on the new site. The author team learns one block instead of five. The performance budget gets one shared CSS file instead of five.

Phase three: dual-run staging

Don't cut over on launch day. Spend two to four weeks with both sites live, the new site behind a feature flag for internal traffic and a percentage of real traffic. Measure RUM, conversion, time-on-page side by side. The new site will be slower than the old site for the first week. Find out why. Fix it. Then ramp.

Phase four: redirects, redirects, redirects

The migration project that "shipped on time" but lost 30% of organic traffic is the migration project that didn't take redirects seriously. Map every old URL to a new URL. Test the redirects in staging with a crawler. Test them again the morning of cutover. Then keep watching Search Console for the next ninety days and fix the long tail of broken inbound links.

Migration projects are not won by elegant architecture. They are won by the team that takes the boring middle phases seriously. The playbook is the playbook because everybody who has shipped one knows it.