Deprecation

The fastest way to remove a feature is to delete it. Teams used to do exactly that, and the cost landed on the people using it rather than on the people who built it.

The scene usually looked like this. On a Tuesday morning a developer at a customer company finds their system stalled. What changed overnight wasn't their code but the API they integrated with — the agreed channel through which two programs exchange data. One removed field has held up order syncing for twelve hours, and nobody on their side remembers an announcement. A change that breaks existing users' code like this is called a breaking change.

The damage stayed with the vendor too. A customer who lives through that once stops trusting the next release note, and from then on even small edits generate support tickets. But removing nothing means maintaining a feature with ten users for years.

Deprecation inserts a stage in between. Things still get removed, but they get announced before they get removed and people get time to move. It's an agreement not to do the announcing and the deleting on the same day.

During this stage the feature keeps working exactly as it did. Two things change: the messaging around it, and the door for new users. People already using it see no difference; people arriving today never find it.

The visible markers go in four places.

1. The help article gets a notice at the very top saying the feature is no longer recommended, with the replacement named. Someone landing there from search has to see it before reading the body, so it goes above the content rather than below it.
2. A banner appears in the product. Show it only to workspaces actually using the feature, and give it one line: how long it keeps working, and what to move to.
3. For an API, the warning rides along in the response. Users who never open a screen and only call the endpoint have no other channel. Put the warning and the planned end date in a response header and the customer's developer finds it in their logs.
4. The path to turning it on gets closed. It comes out of the settings list and stops appearing at all for newly created accounts.

Skip the fourth and the stage never ends. If someone can still switch the feature on today, the count of remaining users doesn't fall and the end date keeps sliding. Announcing and closing the door move as a pair.

That also explains the purpose of the stage. It isn't a courtesy period; it's a work period for driving the remaining user count toward zero. Count remaining users right after the announcement, at the midpoint, and two weeks before the end, and when the count falls slower than expected, find out why on the spot. A clumsy replacement, an invisible notice, and a migration that gets stuck halfway each call for something different.

The next stage is end of life (EOL). Four things have to be in place before crossing into it.

1. The replacement is already running. This is where the order gets reversed most often. Announce the end first and ship the replacement two months later, and there's nothing to say to the tickets that arrive in between.
2. A migration guide exists. It names which buttons to press in which order, and what to look at afterward to confirm the move worked, screen by screen. If something gets lost in the move, it says so.
3. Contracts have been checked first. Where an SLA promises enterprise customers a repair window, setting an end date before that contract expires breaks the promise.
4. Remaining users have been contacted individually. Getting the same wording in a mass email is a different experience from hearing it from your account contact first, and the second one produces replies you can act on.

Fixing the intervals in advance helps. Pagedeck starts the announcement and the deprecation on the same day, sets the end-of-life date 60 days later, and deletes the code 30 days after that. For features enterprise customers depend on, those become 90 and 60. The long gaps aren't an invitation to move slowly — they exist so that someone stuck mid-migration has time to ask and get an answer.

"This field is deprecated as of this version. It still works, but don't use it for new integrations."

It runs today, so don't build anything new on top of it.

"The deprecation notice went out but new workspaces can still enable it. That's the part to close first."

A notice on its own doesn't reduce the user count.

"Six workspaces left, two of them enterprise, so we set the end date 90 days out."

The schedule came from the contracts and the makeup of who's left.

Pagedeck retiring its old document export is a typical run. Mia made the sunset call from usage and maintenance cost, and Theo pulled the list of workspaces that had used the feature in the last 90 days. Forty-one, three of them enterprise.

A week before the announcement, Sofia reached out to those three directly. On announcement day Ravi updated the release note and the help article, and Theo hid the feature from new workspaces the same day. Thirty days later the count was down to nineteen, and half of those hadn't moved because the replacement had no spreadsheet export. That got built first and the end date moved out two weeks.

The most common misreading is hearing deprecation as already unusable. The wording is about an ending, so it sounds like a door that closed today. The stage is defined by the feature continuing to work. Left uncorrected, the mistake causes trouble in both directions: users drop urgent work to migrate immediately and push other commitments aside, while the vendor treats the announcement as the finish line and watches forty integrations stop at once on deletion day.

Treating the announcement as the whole job is the other frequent error. Remember only the rule about giving notice and the notice starts looking like the goal. But the notice is the starting gun; the content of the stage is moving the people who are left. Announce without closing the signup path and the user count goes up instead, and six months later there's a meeting about pushing the date again. A date that slipped once isn't believed the next time, and the announcement after that moves nobody.