Platform teams underestimate how much pain they cause when they deprecate their offerings. You should make deprecation rare and go through a process. Or the team should do the deprecation work itself.
Deprecation improves life for a team, but at an organization cost
A platform team’s natural incentives don’t match the needs of the wider organization.
The team will want to keep their code orderly and easy to work in. They will want to reduce complexity and improve things. Deprecation make life better for the platform team.
Yet, this is dangerous. It is easy for a platform team to create work for the rest of the organization. When they deprecate something, they are creating work on many teams. This type of “fan-out” work is dangerous, because it is expensive and hidden. I have seen product engineering focused 100% on platform projects. I’ve seen company-critical product work delayed due to lower priority platform work.
This is not because the platform teams are dumb or bad. Their incentives aren’t set up right. Platform teams exist to speed up organizations, not to slow them down. So their incentives need to align. Externalizing costs is a moral hazard.
Deprecation is not customer centric
Deprecation is the illusion of communication. It appears to be a kind warning of upcoming changes. But it transfers responsibility for your internal problems to your customers (other teams).
Shifting problems to your customers is the opposite of customer centric. You are requiring them to do work for you.
When you deprecate, you prioritize your work over the whole organization’s work. This is also not customer-centric, because the company’s customers may lose out. You are making a choice with an unknown opportunity cost. For all you know, you could be making a decision that will kill the company.
Sometimes deprecation is necessary
So this may sound like a rant against deprecation, but it is true that deprecation is often necessary. Sometimes technical choices paint you into a corner, and deprecation is your only way out.
You should take this as an opportunity to learn. What decision did we make that required deprecation later? Even if someone else made those decisions, you can learn from them.
And when you do deprecate, you should take great care to minimize the cost on others. Provide simple upgrade paths. Support legacy approaches for as long as you can.
How to handle deprecation
You want to have a system where you can be rational and discuss the impact of deprecation. You also want to minimize externalizing costs.
The two ways I see to solve this are:
Make it hard to deprecate things. Architects or engineering leaders can approve deprecation, for example.
Make platform teams responsible for doing their own deprecation work. This is my favorite approach.
With this approach, if a team deprecates an internal API, they do the work to eliminate all use of that API. If they upgrade a library in a breaking way, they do all the upgrades in their clients.
If you do this, platform teams can deprecate all they want. They’re aware of the cost of deprecation, and they decide when it makes sense. They’ll desire inexpensive and easy upgrade paths. This results in rational prioritization.
Doing this requires funding platform teams at higher levels. They will complain they lack the skills to work across codebases. When you hear that, ask how they can address that problem. Long term, that will be better for the organization.
If the platform team is unable to do the work, they should at least organize and work with the teams doing the work.
Feedback
See anything I missed? Disagree with this? Please let me know your thoughts!
Thank you
Ben Bernard provided feedback on an earlier version of this article, and gave me insight into what he’s seen at Amazon and Google and other places around deprecation. At Amazon they called this “owning your clients”. Ralph Bodenner and I talked through the incentivizes and challenges of getting companies to work this way, and some of the failure modes we’ve seen in the past. He provided feedback on an earlier version of this post.
You can subscribe to more of my posts or join my free engineering leadership course.
Top comments (0)