On writing for deprecation
How to talk to your customers about removing legacy features
There’s something magical about writing the copy for a new feature and then unveiling it for an eager audience. As a product writer or content strategist, this is gratifying work. Who doesn’t like making their customers happy?
But sometimes we have to write for the opposite experience, when a beloved old feature needs to be removed or an outdated version of the product has to be deprecated. It’s unlikely anyone will be delighted with this kind of news.
The decision to deprecate can be complicated and controversial, with internal stakeholders beyond the product team weighing in with financial or operational concerns. Meanwhile, outside the company, people might rely on the feature in their daily lives. It can be disruptive or even devastating when an important tool disappears.
At Slack, we’ve had to remove legacy features and tools, and we’ve had to make hard decisions about which browsers or versions of Slack we can fully support. In the course of writing the copy for these deprecations, I’ve seen how the content, tone, and timing of our messaging play a crucial role in the experience we give our customers.
As best we can, we try to mitigate the pain of the change we’re introducing and gently protect our relationship with the people who use our product. Even if we can’t lessen their disappointment, I’ve come to believe that the following approaches are the considerate and right way to share the news.
Be clear
In crafting the content of your messages, make sure there’s no question about what’s going to happen. When addressing customers, we avoid using jargon like deprecating or euphemisms like sunsetting. It may seem more humane to use softer, more vague language, but in practice it delays their understanding and wastes their time.
We also try to give people the appropriate amount of explanation. In the product, we stick to explaining just the basics. Know your audience, of course; if they’re likely to appreciate and understand a more technical explanation, by all means, give it to them! In our ASCII announcement about closing down the gateways, we ended a bare-bones explanation with a link to a more detailed help page:
In the case of closing down the gateways, the longest section of our message is about the practical question of “what now?” As you might expect, it helps to frame explanations primarily around what the changes will mean for them, not around the details or history of the decision to deprecate. Customers want to know why they should care and if this news will actually benefit them.
Be compassionate
When breaking any bad news, I’ve found it’s crucial for our tone to convey our empathy for the people who are grappling with a situation we’ve put them in.
Handle apologies in a serious, measured way. It’s good to apologize for causing frustration, especially when the changes seem arbitrary or could potentially require something as challenging as a hardware upgrade.
We don’t go overboard with apologizing, though, because we want our apologies to hold weight for when they matter most. Sometimes the task we’re asking people to do isn’t something we should be sorry for — like when we need them to upgrade to the latest version and we’re reasonably certain they can do this with their current hardware.
We used a matter-of-fact tone in the above email to convey that this was a typical notice about updating software — not an unusual problem or error.
Communicate early and often
You can also convey compassion by giving people enough advance notice. Very rarely — if ever — do people enjoy surprises from their software. If a process or feature they’ve relied on is going away, they need time to adjust to the idea and make the necessary changes to how they work.
Be courteous by giving them as much advance warning as possible, and in multiple ways. We’ve found it helps to start early with an in-product banner or dismissible warning dialog. It’s also wise to send an email breaking the news, because not everyone affected will be actively using your product. Depending on the impact and reach of your deprecation, consider running a blog post to explain the upcoming changes in greater detail.
When it came time to close down the stand-alone version of an app Slack had acquired a few years prior, we wanted to give people ample notice. We began displaying an announcement banner in the mobile app sixty days before the actual deprecation:
The message is short and sweet, because the goal is to make people aware of a coming change. Cramming this message with details would have decreased the chances that people would actually read it.
After you’ve notified people ahead of time, you’ll also need to communicate with them after the fact — often in the form of a full-stop dialog. You’re turning a busy thoroughfare into a no-entry zone, so the signage needs to be crystal clear. In this case, we wanted the top takeaway to be that Screenhero’s functionality had been transferred to Slack:
Instead of focusing on the message that Screenhero had been closed down, we framed the headline around the new location for Screenhero-type features: Slack. By presenting it in this way, we gave the interaction some momentum.
Provide a path forward
Keeping that momentum going is key. Instead of simply barring admission, transform your no-entry zone into cul-de-sac: make it easy for folks to turn around and be on their way. It can be tempting to focus on delivering the news, but people also need a next step (other than complaining on Twitter) to help them process the information and move on.
The best-case scenario is when there’s an obvious call to action, like downloading a new version or changing a setting. In this notice about needing to update the Slack app, we offered multiple paths: an obvious button to update on the spot, a smaller link to contact our support team, and two ways to procrastinate (the skip button or the X to close the dialog). Providing a path forward also means letting people defer action until a more convenient time.
In the absence of a clear CTA, you can still provide a link to more information (your help center article, FAQ, or blog post), along with an easy way to contact your support team.
Your final, non-dismissible deprecation notice still needs to make sense to someone encountering the news for the first time. Try not to assume everyone has both seen and remembered the earlier messages — instead, repackage the relevant content in a way that stresses the finality of the situation.
While there’s no way for people to get around this message and into Slack, it’s very clear that they can either update the app or reach out to customer support.
Thoughtful and intentional pruning of an app is challenging, but in the end it’s also fruitful for both the customers and the business. Deprecating legacy features makes it possible for internal teams to raise the overall quality bar and create a more consistent and reliable product — while freeing those teams to focus on the company’s top priorities.
By crafting copy that’s clear, helpful, well-timed, and empathetic, you can lead customers through a potentially challenging interaction in a way that minimizes their frustration. And then you can get back to building and perfecting a product they’ll love.
Want to help us build a well-loved product? We’re hiring!
