Ask HN: Advice for leading a software migration?

Planning is important, and avoid committing to targets or deadlines until you have your arms wrapped around what needs to be done. This can be wide-ranging, and include: product parity, contract management, internal asset development (project plans, test suites, customer training, etc.), customer change management, and team throughput.

You have few clients but large impacts. You likely want to pick the friendliest one and give them generous terms to be the "test case". Expect it will take 2x longer than your estimate.

Do as much work on parity as you can: what are the differences between v1 and v2, and how will you bridge them? If data migration is involved, you will need tooling and team training.

Inevitably you will find that customers move slower than you like and are using v1 in ways you did not expect.

PM: "Fill out this spreadsheet with key dates leading up to the project completion."

Me: "First, that's your job, not mine. Second, I literally just got here, I haven't even drunk my coffee yet. Hi, my name is Jiggawatts. I've only just heard of this software we're migrating ten minutes ago."

PM: "Yes, yes, but the customer asked me for cost estimates and timelines."

Me: "I asked for a Lamborghini packed with supermodels, but I didn't get that either. Tough break, huh?"

PM: "It's not an unreasonable request!"

Me: "Without time machines and/or a magic crystal ball, it is. Do you have a time machine?"

Etc...

We all recognise this, and it's a symptom of an underlying problem.

Really, what ought to occur is incremental progress and demonstrable deliverables. If you go off into a cave for two years and come back with something the customer doesn't like, then you've caused a business catastrophe.

I've found that businesses and customers in general prefer incremental improvement. One trick in .NET land is to use something like YARP[1], which lets you totally rewrite the app... one web page at a time.

Another management trick on top of that is to not demo the last few steps. Complete the last few milestones of the project quietly, without reporting this up until the very end. I guarantee you that everyone in charge of the budget thinks they can "save money" by skipping the "last 10%", even though that results in 2x the ongoing complexity because it means the legacy components must still remain live and deployed to production.

I guarantee that the only way to prevent this is to lie to management. It is biologically impossible to insert these concepts into the brain of a non-technical manager, so don't even try.

[1] https://microsoft.github.io/reverse-proxy/

To the extent possible, prioritize complete vertical slices. While it may not be feasible for foundational or generic technology layers that must be fully developed before building on them, aim to avoid focusing on large horizontal layers that delay end-to-end functionality or demonstrable results within the new system.

Again, depending on many factors, you might consider the strangler fig pattern, in which you implement some component of the new system and operate alongside the original one, route some usage from the old to the new (or even run in shadow), test and validate, repeat incrementally, and so on.

In my mind, what it comes down to is just being really vigilant in ensuring you minimize the risk inherent in a massive migration...which basically means try to achieve the ultimate migration with a series of much smaller, iterative migrations that carry significantly less risk.

Having led my fair share of migrations in the past and going through one right now, here are my tips.

- Understand your stakeholders and the teams that are impacted. Spend enough time understanding how the system is being used today. Proxying and abstractions are you friend here. Just get as much data as possible.

- Once you get enough data, make sure to crunch and very importantly, have a means to surface this to the users. More often than not, for systems that have organically grown, you'll be surprised that users themselves don't know how they use an API.

- As much as possible, try to move things seamlessly. You can always do some portion of the migration without users knowing it. This can be as simple as introducing a translation layer or even you making code changes for the users to review them.

- If you're working on a timeline here owing to external factors like vendor contracts, cert expiry dates etc., make sure to buffer in at least a quarter (or possibly more). There will be new discoveries along the way.

- There will always be teams/stakeholders who will oppose to you asking them to do this work. I can't stress this enough - make sure to get your leadership on board. If you have a Program Management Office, make them your best friends. For anything that escalates and gets political, you as an engineer are better served to get the job done and an aligned leadership that backs you will help you fight these stragglers.

- Ultimately, love what you're doing. There's a mistaken understanding that migration work is not as sexy as greenfield work. I truly believe greenfield work is manifold simpler than migration. A migration is more like changing the wheels and the engine of a car as its running. There will be a lot of tradeoffs that have to be made and this is where engineering skills come into the picture!

All the best! :)