Communication Plans for Major System Migrations

Contributor
May 20
6 min read

The autopsy of most failed migrations reads like a technical document, but the failure mode is almost always communication. Customers learned about a breaking change in a status page two hours after their integration broke. The support team got a Slack message ten minutes before launch. Finance discovered three weeks later that the new billing system rounded differently than the old one.

A communication plan is the boring artifact that prevents this. It's not glamorous; it doesn't ship code. But the difference between a migration that lands cleanly and one that creates a year of cleanup is usually whether someone wrote and executed a real plan.

What a Communication Plan Is For

The plan answers four questions for every stakeholder group:

Who needs to know?
What do they need to know?
When do they need to know it?
How will we tell them?

That's the entire framework. The detail is in filling it out for each audience, and the discipline is in executing it.

Identify the Audiences

Audiences aren't generic. "Customers" isn't an audience; "API integrators of the old endpoint" is. "Internal teams" isn't an audience; "the on-call rotation, the support team, the finance reconciliation lead, and the data team that depends on the old schema" is.

The first deliverable of a communication plan is the list of specific audiences, by name where possible. If you can't name them, you don't know who you're communicating with.

For a typical major migration, the list includes:

Direct users of the system being migrated
Indirect users whose systems depend on the one being migrated
Operations — anyone who runs, monitors, or supports the system
Support — the people who'll get questions when things change
Finance, legal, compliance — anyone who needs the old or new state for their work
Leadership — people who need to know the migration is happening for visibility, not action
External partners — vendors, integrators, or downstream services

Each audience gets its own row in the plan.

Match the Message to the Audience

A single message doesn't work for all audiences. The technical detail that engineers need would overwhelm a customer. The high-level framing that leadership wants is useless to a support rep.

For each audience, define:

Their concern. What are they worried about? What do they need to plan around?
Their level of detail. Engineers want the technical truth; executives want the strategic framing.
Their action item, if any. Reading is not an action. What do they need to do?

A customer email might say: "We're upgrading our authentication system on June 15. You don't need to do anything. The first time you sign in after the upgrade, you may be asked to re-enter your password. If you have any integration scripts that automate sign-in, they should keep working without changes."

A support team brief might say: "On June 15 we're moving from session-token-X to session-token-Y. The user-visible symptom is a forced re-sign-in. The first 48 hours will likely have elevated 'I'm locked out' tickets. Here's the runbook for resolving them: [link]. Escalate to oncall-auth for anything not covered."

Both communicate the same migration. Different audiences, different content.

Define the Cadence

A communication plan has timing, not just content. The same message at the wrong time has the wrong effect.

A standard cadence for a major migration:

T-30 days: initial announcement to internal teams. Stakeholders learn the migration is happening, scope, dates.
T-14 days: customer pre-announcement, if applicable. Detailed enough to plan around, not so detailed that it becomes obsolete.
T-7 days: operations and support readiness check. Final escalation path confirmed. Runbooks rehearsed.
T-1 day: day-of reminder. Status page updated to "scheduled maintenance" state if applicable.
T-0: migration in progress. Real-time updates in agreed channels.
T+0 (cutover): confirmation that the migration is complete. Verification evidence.
T+7 days: post-migration retrospective summary. What went well, what didn't, what we'd change.

Adjust the cadence to the migration's size. A small migration might compress this to a week. A regulatory-driven migration might need six months of lead time.

Use the Right Channels

Channel matters as much as message.

Email for things people need to reference later. Customers, finance, partners.
Status page for customer-visible operational changes. Don't bury bad news.
Slack/Teams for internal coordination. Pin the relevant message in the relevant channels.
Calendar invites for windows people need to plan around. Operations and on-call.
Documentation for the durable reference — the runbook, the migration guide, the changelog.
Video/town hall for changes that affect a large internal audience and need framing.

The mistake: sending everything in one channel. The most important migration of the year buried in a Slack thread that 80% of the affected team will miss is the same as not communicating it.

What Customer Communication Should Include

Customer-facing communication has a specific structure that works:

What is happening. Plain language. No internal jargon.
When it's happening. Specific date and time, with time zone.
What they need to do. "Nothing" is a valid answer if it's true. If it's not, be specific.
What they'll see. The visible symptom of the change.
Where to go for help. Support email, status page, documentation link.
Why we're doing it (optional). If the benefit is real, mention it briefly.

What customers don't need: the technical architecture, the migration plan, the team that's executing it. They want to know how this affects them and what they need to do.

What Internal Communication Should Include

Internal teams need more detail than customers, but the structure is similar:

What is happening, in technical terms.
When it's happening, with the cutover window.
What's affected. Specific systems, integrations, dependencies.
What the operational impact is. Performance, error rates, escalation patterns.
What to do if something goes wrong. Specific runbook or escalation path.
Where to ask questions. A channel, a name, an office hour.

Internal communication should also include "what's not changing." This prevents the team from inventing problems that aren't real.

Drafting Templates in Advance

The best time to write the customer message about a migration is when you're calm — before the migration window. The worst time is when something is going wrong at 2am.

For each major migration, draft in advance:

The customer pre-announcement email
The day-of status page update (for normal execution)
The day-of status page update (for delayed or rolled-back execution)
The post-migration summary
The "something went wrong" customer email (used only if needed)

The "something went wrong" template is the most important one to have ready. In an actual incident, you don't have time to write a thoughtful customer message; you need to ship it and get back to fixing the problem.

Assign Ownership

A plan with no owner is a wish. Each communication in the plan needs a specific person responsible for:

Drafting it
Reviewing it
Sending it on time

For larger migrations, this is enough work to be someone's actual job for the duration. Don't bolt it onto the project lead, who already has a different full-time job during the migration.

Track What Was Sent

Keep a log. For each communication: who sent it, when, what audience, what channel. After the migration, the log is the evidence of how communication happened, useful for the retrospective and for the next migration's plan.

Logs also catch the omissions. "We didn't actually send the customer pre-announcement" — that's a problem you want to catch before T-1, not in the post-mortem.

The Things That Always Get Missed

In every migration retrospective, the same audiences get missed:

The customer who integrated against you years ago and you've forgotten about.
The internal team that built a dashboard against your old schema.
The vendor who has a webhook pointed at the old endpoint.
The auditor who needs evidence of how the change was communicated.
The team that's on PTO during the change and comes back to a different system.

The first three are caught by an honest dependency analysis. The fourth by including compliance in your stakeholder list. The fifth by running the migration during a window that respects the team's calendar.

Key Takeaway

A communication plan is a structured answer to four questions per audience: who, what, when, how. Identify specific audiences by name, match the message to each, define the cadence, and use channels that fit. Draft templates in advance, including the "something went wrong" version. Assign ownership and keep a log. Most failed migrations aren't technical failures — they're communication failures. A boring but real communication plan is one of the highest-leverage artifacts you can produce.

ShiftQuality