The Day Your Software Dies
“We act like our software will last forever,” technology writer Daniel Beck said at the APItheDocs London conference. But what do we do when the plug is finally pulled?
When folks in our biz get together to talk about documentation, we like to talk about the beginning — onboarding etc — and even the mature years — advocating for a new feature. But we don’t talk about the end. But pretty much everyone has experienced the loss of a tool they’ve come to rely upon.
So how do you as a technical marketing professional, or a customer-facing project manager, treat this in the way you wish you’d been treated?
To start, think of any major deprecated features or versions as similar to a full shutdown in the eyes of your user. Now that you’ve done that, consider some of the things Beck says you have to get just right in order to do your team and your customers a service.
With Software Shutdowns, It’s All about the Right Mindset
So you may be excited your company got bought and you have a great pay raise, but that doesn’t mean everyone on your team is welcoming this change, let alone your users.
In those cases where an acquired company has to shut down a line of software, the marketing team must work hard to “manage your response to your team and users — just because you’re having an easy time with this, doesn’t mean they are.”
Start by talking with your team about what the shutdown is and what it means for them. If they need new jobs, they need to know that ahead. And if they get to keep their jobs, you can give them peace of mind and keep them on your team for the big move, if you tell them earlier.
And, once you’ve communicated with your team, by all means, buy yourself as much time as possible. Whether your company is shutting down or shipping out, as a team leader, you may be getting forced to document and roll out the shutdown or depreciation as fast as possible, but don’t be afraid to push back to get more time to do it right.
Next, when it’s time to time dive into the dirty work, think of your users every second.
“As a tech writer, it’s not often that you get to write something that every single one of your current users has to see and understand.” — Daniel Beck
And don’t forget to work with your support team because they will be the front line.
Finally, Beck reminded us to work with operations, as they will be making the technical decisions that you’ll then be communicating to your users.
The Last Thing You Want to Deprecate Is Your Communication
A software or API shutdown isn’t a place for do-overs. You get one chance to shut down your project. This is why Beck says you have to plan well your communication of it all.
First, as soon as you know the shutdown is coming, you or your marketing team needs to turn off any existing outreach. You may have scheduled continual tweets about your product and its features. You may have an email drip campaign that compels an upsell like added customer support. You may have banner ads on websites, podcasts or blogs like this one. You need to pause all outreach, not wanting to attract new customers — or distract the current ones — when you are trying to shut things down.
Next, use all those same customer outreach channels to communicate this change, reminding people that it is coming. Utilize all your support team’s channels any in-app communication. Beck also pointed out that sales often has good relationships with customers and should be leveraged for individual customer contact.
Using the example of a deprecating application programming interface, he offered the specific example of messages, like creatively placing a reminder in the user interface: “This token is expiring within three weeks” — not the three years your users may have come to expect.
You can even put reminders in your status messages or error reports. If you have a big enough community, be sure to bring it up at industry events.
And, of course, don’t forget to put the notification at the top of your documentation.
Once you’ve planned how you can communicate, it’s time to plan when. Beck suggests mapping out an escalation strategy.
When should you not communicate? Any public holidays — both yours — like Ramadan is a bad idea if your tech support is in the Middle East — and your users. Make sure you aren’t making any big announcements when key staff has booked time off. Plus, Beck says, since this time is stressful, block every Friday afternoon off until you’re through to the other side.
Don’t forget to include support in your scheduling, as they will be the ones who have to deal with the blowback.
Now that you know when not to communicate, start communicating the dates when you’ll start doing things, removing things or taking them down. He recommends doing “Starting on this date…” or “No earlier than…” dates rather than hard deadlines. These are dates where you no longer will guarantee something, but without making more promises you can’t keep.
Beck reminds you to “Be calm, gentle and direct to your readers.”
No one wants your sob story. And no one wants your start-up cliche of an “incredible journey.” Any change may be positive or negative for you, but it’ll definitely be disruptive for your users.
“It really does not need to be about you, it’s gotta be about them,” Beck said.
This is the time to stick to just the facts:
- What is happening? in concrete terms like the API is going to stop responding to requests, no more support from this date, you’ll receive a final bill on this date
- When is it happening? List the dates and milestones.
- As a user, what do I need to do?
If you really want to be a star, Beck even suggested considering working with your previous competitors to work together to write a migration to an alternative service. Now that’s putting your customers first through to the end!
He ended his talk by saying that you will get asked why a lot. But don’t feel obliged to answer it. That’s for you and your team to decide what you want to share. You just owe your users the What? When? and How?
And, of course, you must show your gratitude.
After all, once this is said and done, Beck pointed out that “The worst case scenario is nobody cares.”
Thank you also to Erik Wilde for offering this great example of sunsetting your API by making a machine-readable announcement.
