Thread by @Lethain

Software migrations are a way of life at rapidly growing companies, and increasingly I think your ability to migrate effectively is the defining constraint for your growth.

lethain.com/migrations/

Teams hate tech debt. If they can locally reduce it, they'll do it. So at some point all remaining avenues to reduce tech debt require ~everyone simultaneously adopting a new platform: migrations! Moving everyone? A *lot* of coordination!

My approach to migrations is three phases: (1) derisk it by ensuring the approach can succeed, (2) enable the change by building tools and automation, and (3) finish the damn thing while minimizing disruption to other folks. (Migrations are rarely other folks top priority.)

Starting migrations by generating tracking tickets for teams to implement? Please don't. Write a design document and shop it with the teams that you believe will have the hardest time migrating. Iterate. Shop it with teams who have atypical patterns and edge cases. Iterate.

Next step is to embed into the most challenging one or two teams, and work side by side with those teams to build, evolve and migrate to the new system. Don't start with the easiest migrations, which can lead to a false sense of security.

Now slow down and build tooling to programmatically migrate the easy ninety-percent. This radically reduces the migration's cost to the broader organization, which increases their success rate and creates more future opportunities to migrate.

Once you've handled as much of the migration programmatically as possible, figure out the self-service tooling and documentation you can provide to allow folks to make the necessary changes without getting stuck. The best migration tools are incremental and reversible.

Documentation and self-service tooling are products, and thrive under the same regime: sit down with some teams and watch them follow your instructions, then improve them. Find a another team, repeat. Spend an extra two days making your documentation clean and tools intuitive.

Finally, you need to finish! Start by stopping the bleeding, which is ensuring that all newly written code uses the new approach. That can be installing a ratchet in your linters, or updating your documentation and self-service tooling.

Ok, now generate tracking tickets. Give the management team context around migrations: they are the folks who need to prioritize the migrations; if a team isn't working on a migration, it's typically because their leadership has not prioritized it.

At this point you're pretty close to complete, but have the long tail of weird or unstaffed. Your tool now is finish it yourself. It's not necessarily fun, but getting to 100% is going to require the team leading the migration to dig into the nooks and crannies themselves.

My final tip for finishing migrations is around recognition. It's important to celebrate migrations while they're ongoing, but the majority of the celebration and recognition should be reserved for its successful completion.

btw, I think it's easy to view frequent migrations as a sign of bad architecture, and sometimes they are, but sometimes they're just the sign of rapid growth and appropriately designed systems whose constraints have rapidly changed.

lethain.com/productivity-i…