When we last saw Uncle Steve on his ladder, I left him a set of instructions about a less-risky way to adjust the ladder. Interestingly, these instructions roughly translate into a fairly useful technique for platform developers. I call it the platform two-step after a dance move, because platform development is a lot like dancing: both a skill and an art, and only fun when you’re into it.
This technique is something I find employed quite often by teams that make developer surfaces. Like the dance move, it is fairly intuitive and goes like this: if you desire to change an existing API, you need to first introduce a new API so that two are shipping in parallel (one foot steps out), then remove the old API (the other foot joins the first one). Simplifying it even more: to change, add one, then remove one.
This feels fairly straightforward, and appears to work nicely around the hazards of moving-the-ladder scenario we encountered with Steve. At the core of the technique is the realization that once shipped, APIs are basically immutable. Should we recognize that our first take on the API misses the mark, the only choice we have is to ship an improved API first, and then work to remove the first iteration.
In my experience, having patience between the two steps is where most platform teams struggle. While it may take time to ship a feature, the time to remove it is usually longer – and sometimes much longer. This was a hard-learned lesson for me. In early 2011, a few of us championed a set of specs we called Web Components, shipping them in 2014. We didn’t get it right and it took the Chrome Web Platform team until early 2020 to finally remove that iteration of the API. Some removals take even longer. The Web SQL Database is finally being removed this year, having enjoyed the “remaining foot to join” status for over a decade.
While bearing this patience, a rather unhealthy dynamic tends to develop. Because the cost of removing APIs is so high, we can’t afford to ship APIs that miss the mark. Especially when already playing a catch-up game, every new feature of the layer that doesn’t inch the vector of intention toward the user value is considered an opportunity cost. A typical symptom here is the platform developer edition of analysis paralysis, where new APIs are scrutinized extensively while under increasing pressure to “ship something, darn it!” APIs end up being over-designed and late because of the fear of missing the mark, translating into more fodder for deprecation, thus resulting in more resources being sapped from the API design.
I have observed teams stuck in that vicious cycle and I have been in them myself. The seemingly glacial pace of can be quite frustrating and appear as if the whole organization is about to seize like a giant rusted machine. The toil leaves little room for long-term thinking, with everyone just barely putting one foot in front of the other. It’s less of a dance, and more of a cruel march.
My intuition is that the way out of this situation lies through learning how to deprecate effectively. To complete the two-step, I need to learn how to migrate developers from one API to another. Put differently, in the platform two-step, the most important practice hides between the steps. Deprecation is hard work, and may seem mostly useless, because it takes away the resources for very little visible gain in the layer’s never-ending pursuit of adjusting its vector of intention. Folks who only measure a team’s success in features shipped will view deprecations as a distraction, or at best a “necessary evil.” If an organization’s culture was established during the rapid growth of a new-frontier platform, advocating for deprecation can be a tough sell.
When I want to know if a team knows how to evolve platforms, I look for things like the presence of deprecation processes, accompanying telemetry, and deprecation accomplishments celebrated on the same level (or above!) as shipping new features. A special bonus: a platform design itself considers deprecation, and perhaps even offers some novel insight that advances beyond this classic two-step technique. Perhaps a platform moonwalk of some sort?
One thought on “The platform two-step”