Where to find it
https://lethain.com/migrations/
What’s it about?
Really, the name says it all. It’s a great article about fixing tech debt.
In this article—which is also featured in his book An Elegant Puzzle—Will Larson doesn’t spend much time describing technical debt, but instead goes straight for the deep dive into how to fix it.
My thoughts
I love this article. As always, Larson shows his keen insight. When working on platforms in particular, I reference this article a lot.
The whole playbook is great: Derisk ▶ Enable ▶ Finish.
It’s worth noting, however, that migrations require a lot of buy-in. I’d recommend starting with crafting a compelling story first.
The playbook
Derisk
Before we can run an effective migration, we’ve first got to convince the folks to use your shiny new thing instead of what they’re already using. This is sometimes the hardest part because it’s a people problem, not a technical one. You’ve got to understand your “customers” for the migration.
What problems do they face? What concerns do they have with using the new thing? What pain points do they have with the old one? How much bandwidth do they have to commit to the migration themselves?
This is where Design Documents come in handy.
Enable
This is the most exciting part to me. Here, we get to automate the change! When I’ve done this in the past, it’s taken the form of code generators. I don’t know what it is, but something about writing tools to consume and output code makes me irrationally happy.
At this point, it’s important to focus on automating only the easy 90%. When we get into rare, hard-to-automate corner cases, it’s usually best to write documentation on how to do it manually.
Finish
And here we reach the least pleasant part.
The first thing to do in this phase is to Stop the Bleeding—a concept which I love enough to write about separately. Once all new work is using the shiny new thing, we’ve got to do the usually-unpleasant chore of cleaning up the last few stragglers. And because these are the ones that weren’t automated, they’re the hardest.
Larson drops one last little gold nugget at the end here that I believe is worth restating in its entirety:
Quote
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. In particular, starting but not finishing migrations often incurs significant technical debt, so your incentives and recognition structure should be careful to avoid perverse incentives.
Storytelling comes first
Like I mentioned earlier, I would have liked to see more about convincing the decision makers when it’s time for a migration. Unless you have full control of what you and your team work on, crafting a compelling story is the first real step to this kind of change.
Larson’s article seems to skip over the time before a migration is really needed. I’d recommend starting with Jacob Kaplan-Moss’ way until it becomes clear that a migration is required. It will be eventually, but now may not be the time. Now may be the time to plug the slow leaks in this ship until it is time to get a new one.
If nothing else, measuring the impact of your tech debt will make a more compelling argument for spending time paying it off, and that’s always important for ensuring you and your team are working on the right things. “I don’t like it” isn’t a good reason. “Our change failure rate has increased by X% in the last quarter” is a good reason.
Once you’ve got the buy-in you need to start migrating away from your crusty old system or tool, I highly recommend Larson’s playbook here.