Daniel D. Beck

What does “deprecated” mean to your readers?

All good things come to an end, including software features, APIs, and whole products. From deprecated to end-of-life, there are lots of words you can use in your documentation to tell readers that something is going away, but there’s no consensus pick. What’s the right term to tell your readers that the end is near?

Unfortunately, style guides won’t provide much help when it comes to deprecation. They’re often silent on the topic, or provide very narrow guidance on word choice. For example, the Microsoft Style Guide says to avoid deprecated, but provides no additional detail.

You can always ape the style of well-regarded docs, but you won’t know why the authors flagged a feature the way they did. It’s especially troublesome because there’s a gradient of seriousness from “there’s a better alternative feature available”, through “this is bad and you shouldn’t use it if you can help it”, to “we’re removing this feature and your application will break if you continue to use it.” Capturing that seriousness in a few words takes care.

And failing to take care can make it hard to be taken seriously. No matter what you write, there’s always going to be someone doing a panicked, last-minute upgrade, but you don’t want to be blamed for inadequate warnings.

Fortunately, there’s a pattern you can follow, independent of word choice, to clearly communicate the significance and gravity of a deprecation.

Lots of options, fewer meanings

Not too long ago, I was presented with evidence that my readers were confused about the way we used the word deprecated. To learn more about the problem, I turned to the Write the Docs community for help. I asked fellow documentarians what terms they’re using for deprecations and what they meant by them. I got a possibly exhaustive list of possible terms:

Yet the variety of terms didn’t reflect a variety of usage. Most used their selected term to mean:

There were some departures, however. Some writers added that deprecation meant a withdrawal of user support; in other words, use at your own risk. A few dissidents said that deprecation was the moment of removal (or after), when something has gone away and cannot be used, not merely discouraged (an approach I don’t like, but more on that soon).

An added wrinkle was the notion that something will go away in the future—a wrinkle that directly related to my problem in the first place: the future may be indefinite. You might ask readers to understand that something will or could go away in the future, even if, in practice, deprecated things are never actually removed. A typical example is when an API is deprecated, but retained indefinitely for backwards compatibility. In such cases, deprecation is a way to discourage use.

The variety of terms and the subtle differences between them leads to a troubling conclusion: terminology alone won’t communicate to your readers your project’s approach to deprecation.

Rely on carrots and sticks, not terminology

Instead of relying on terminology alone, speak directly to the complications imposed by deprecation, not your release schedule. Think like one of your readers: What can I do today? What will happen in the future? How do I cope with what’s changing?

Follow a pattern that addresses those questions for a deprecated feature, API, or product:

  1. Describe the status, using the terminology of your choice, and make a recommendation.
  2. Suggest an alternative, if one is available, and highlight a benefit to switching.
  3. Name the consequences of sticking with the disfavored feature.

Here’s an example, for a fictional API for managing mailing addresses:

The SendToAddress API is deprecated, so don’t use it in new integrations. Use the ShippingAddress API instead, which works with more international addresses. The SendToAddress API will stop working in 2022.

And here’s that same example, broken down:

"The SendToAddress API is deprecated…" is the part that names the status. "…so don’t use it in new integrations" is the part that makes a recommendation. "Use the ShippingAddress API instead…" is the part that suggests an alternative and "which works with more international addresses" is the part that shows the benefit of the alternative. "The SendToAddress API will stop working in 2022" is the part that names the consequence.

The precise format doesn’t matter so much. You could use a Deprecated label next to an API name instead of a sentence, for instance. But you should do something that covers each part of the pattern: status, recommendation, alternatives, benefits, and consequences.

This pattern works to prepare your readers for features reaching the end of their useful life in the future, but it doesn’t work for things that are already gone. For those cases, we need a different approach.

Don’t document things that don’t exist

As far as your users are concerned, once a feature is gone, it’s not deprecated, legacy, obsolete, or anything else: it doesn’t exist. Documentation that covers historic features are, at best, distractions to getting things done today.

In general, archive or delete content that covers historic features. You can make exceptions for versioned docs, which ought to reflect the state of the software at each version, or a brief grace period when content might outlive the features they relate to (you’re busy, I know).

That doesn’t mean you have to yank the rug out from under your users, however. You can use redirects to guide readers to the alternatives that you would have put into words before deletion.

On the road to removal

To summarize, when you’re on the road to removing something remember these keys:

Lastly, if you want to learn more about shutting down an application or service, check out my Write the Docs talk on shutdowns and deprecations.