Migration Guide

For the team removing a feature, the decision was the hard part and telling people feels like the last item on a checklist. So announcements used to read like this: "The existing export feature will be retired on March 31. Please use the new export instead."

The person reading it is in a different position. They have pressed the same buttons in the same order every month for three years, and they hand the output to the finance team or load it into another internal system. One line of announcement leaves every real question open. Where is the new feature? Does the scheduled delivery already configured still run? If the file format changes, does the finance team's template have to change too? Will three years of history be visible on the new side?

Pagedeck got all of those at once. The week after an announcement went out, half the calls Sofia took opened the same way: "You're telling me to switch, but I have no idea what I'm supposed to do." With no document to point at, she screen-shared through it one customer at a time, and only after the thirtieth repetition did anyone suggest writing it down.

A migration guide turns those thirty conversations into one. The announcement says what ends and when; this document answers what to do about it now.

Six things belong in the document. Anything left out comes back as a support conversation.

1. What ends, and when — feature name and dates at the top. Record the deprecation date when the feature stops being recommended, the end of life (EOL) date when breakage stops being fixed, and the day it actually disappears, as three separate lines. Collapsed into one, the reader can't work out how much room they have.
2. A mapping to the replacement — each piece of the old feature paired with what it corresponds to in the new one. If scheduled delivery exists on the new side under a different name, such as an automation rule, that belongs in the table rather than buried in prose.
3. The steps to move — which screen, which button, in what order, numbered. Procedure, not explanation. Screen names have to match the product exactly, and if a step needs administrator rights, say so at that step rather than in the preamble. A condition announced once at the top is forgotten six steps down.
4. How to confirm it worked — what should be visible if the move succeeded. Last month's records still listed, owner names preserved, and so on. Without this, people stay unsure and keep using the old feature alongside the new one until the day it shuts off, which is how a sunset reaches its deadline with the usage numbers barely moved.
5. What gets lost — anything that disappears or changes shape in the move, stated up front. If timestamps on old comments only survive to the minute in the new format, write that. Learning it beforehand is a decision; learning it afterward is a complaint.
6. Where to get help — who to ask and how quickly an answer comes back. Customers covered by a service level agreement (SLA), the service quality promised by contract, get pointed to their own channel.

The first draft comes from whoever decided to remove the feature. At Pagedeck, Mia fills in items 1 and 2, because only the person who made the call knows exactly what ends and what replaces it. Theo fills in 3 and 4 by clicking through the real screens, and Ravi handles the wording and the links from help content and the release note. If enterprise customers are involved, Sofia reads it before the announcement and adds steps to item 3 where she expects her accounts to stall.

Readers fall into three groups.

1. The person who used the feature — they want the procedure. A long background section above it means they never reach step 3 and open a ticket instead.
2. The account administrator — they are moving settings for a whole team, so they read the losses and the dates first. They also have to re-announce internally, so wording they can copy straight out saves a second round of work, and a short summary near the top is usually what ends up in that internal message.
3. The support agent — they use it as a script when a question arrives. It gets linked from a support ticket constantly, so headings that can be linked to individually cut response time.

"We can't announce before the guide is ready. We'd have nothing to answer with."

Holding the sunset until the replacement path and the steps are written down.

"Step 3 doesn't mention needing admin rights. Everyone stops right there."

The procedure has drifted from the actual screens, and users stall at the same point.

"Don't just send enterprise accounts the link. Have their contact reach out first."

The same document lands differently depending on how it arrives.

The quarter Pagedeck closed its old export, the document came first. Mia posted a draft, Theo followed the steps and added two he had missed, and Sofia pointed out that the change in the file template handed to finance teams was nowhere in it. That one line went into item 5, and when the announcement actually went out, inbound questions ran a third of what the previous sunset had produced.

The most common mistake is treating the announcement and the guide as one document. Both tell people something is ending, so merging them is tempting. But they are read at different moments. An announcement is read once in passing and has to stay short; a guide is opened again on the day of the move and kept on screen, so length costs nothing. Merged, the announcement grows long enough that nobody finishes it, and the address people need on moving day is lost somewhere in an inbox. Leave dates and a link in the announcement and push everything else into the guide, and both do their job.

The name also invites confusion with a database migration. That one moves a storage structure into a new shape and is engineering work; this document helps a person move to a different feature. Same word, but what moves is data in one case and users in the other. The distinction matters in planning, because a database migration finishes on the day it runs while this one finishes only when the last account has actually switched, and that date is not under the team's control.