Migrating Legacy Services
An Exercise in Decision Making
Hey, I’m Colin! I help PMs and business leaders improve their technical skills through real-world case studies. For more, check out my Live cohort course and subscribe on Substack.
I seem to gravitate towards working products that require migrations. Whether moving a health system from paper to digital records, or shifting millions of monthly transactions to a new recommendation system, I’ve done my fair share of legacy migrations.
Today I want to share 4 key steps to a successful migration and outline a few common patterns I’ve seen work well. Finally, I’ll wrap up with some additional resources that I’ve found helpful as I navigated this space.
Step 1) Problem Statement
Almost every migration starts the same way - the old way is bad. If we just rebuilt it, it would be better.
I’ve seen this come from engineering frustrations with legacy systems, product frustrations with shipping slowly, and business frustrations at being tied to high cost systems and processes. It can be deceptively simple to get everyone to agree that a migration is a good idea.
Unfortunately, each stakeholder group is thinking differently about what the migration means for them. Without clear alignment on what outcome the migration will produce, you’re likely to lose trust partway through the project. It’s essential that you have clearly defined benefits for the business and product. This includes clear, measurable financial or customer benefits, as well as internal benefits.
The best way to document this is with a clear problem statement (or paragraph). This should outline the current state, future state, and expected benefits.
You should also consider if there’s other ways to reach this outcome. Is a migration really the best way to improve engineering velocity or reduce costs? What other options are available to solve this problem?
Step 2) Explore Your Options
Once you have alignment on what outcomes the migration should produce, it’s time to think through your options. This is the space where you want to exhaustively explore the solutions available to you.
One method I typically start with is brainstorming the following options:
Do nothing - keep everything the same
Cautious case - Low effort
Optimistic case - Medium-high effort
10x case - swing for the fences; invest the most possible to get the most benefit
Another method is to use common migration patterns, such as the Strangler Fig. This approach requires you to build a shared layer that can pass requests to the legacy or modern service. Over time, you decrease use of the legacy service until it can be removed entirely. This can be fit into the framework above as your optimistic case.
One of the biggest mistakes I’ve made on past migrations is not being exhaustive at this step. There is nothing quite as painful as realizing part way through a migration that you could have saved months of effort if you had taken a different approach.
Step 3) Gather Data & Test Assumptions
Now that you have a set of available migration options, you want to gather data on each and test your assumptions. You likely already have a preference for a specific decision at this stage, but it's important not to get tied to any solution too early.
Typically, the data you want to collect includes:
How long will this option take?
How much risk is associated with this option?
How well does this option solve our problem?
What are the expected benefits?
Through no fault of their own, engineering often underestimates how long it will take to migrate a legacy service. I’ve found that these projects neatly follow the 80/20 rule - expect that you can finish 80% of the requirements within engineering estimates, and 100% at 1.5x - 2x the estimate.
Step 4) Over-communicate & Execute
It’s time to make a decision on a path forward. Assuming you’ve completed the step above, this should be relatively easy. There’s typically only one or two viable options that require debate. It’s worthwhile to review these live with critical stakeholders to build buy-in.
Another critical step is to over-communicate this decision. You’re unlikely to know every dependency on the legacy service, so it’s important to get out in front of any issues. Publish your plans as widely as possible and ask for input across the org.
Finally, start using your new service as early as possible on a small scale. You’re unlikely to discover every undocumented business rule in the legacy service, so get your product out into the world with clear plans for rollback if things go wrong. Nothing’s worse than going away for 6 months, only to launch and find out you missed critical requirements.
Common Patterns & Resources
If you’re interested in learning more, check out my upcoming Lightning Lesson on Oct 15th to get hands-on practice applying this approach to decision making!
For more resources, see: