How to write a migration guide that answers switching objections

A migration guide that answers switching objections is a public page that takes a buyer through four worries in order: what to prepare before moving, whether their data comes with them, how much effort the move takes, and how to go back if it goes wrong. Write each part from the questions buyers actually raise, state only what your product does, and mark plainly what you cannot promise. The guide is a hypothesis about what reassures buyers, not a guaranteed way to win an AI answer or a customer.

In short

• Switching buyers often object about risk and effort more than features. A migration guide should be organised around those worries.
• Use four sections (preparation, data portability, implementation effort, rollback) and give each one a concrete answer, a limit, and evidence.
• Take your objection list from what AI engines say when asked for downsides, then check it against your sales and support notes.
• Never name or compare other vendors. Describe the move from "your current tool" in general terms.
• Treat every claim as something a reader could verify. Anything you cannot prove yet belongs in a "what we cannot promise" note.

Why do switching objections need their own page?

Because the question "should we move?" is different from "which product is best?", and a feature page seldom answers it. A buyer who already uses a tool is weighing the cost of leaving as much as the value of arriving. Their questions are about risk: will our history survive, how long will people be distracted, and what if we regret it?

If you leave those questions unanswered on your own site, buyers may fill the gap from other places, and AI engines may too. A migration guide is a page or short series that explains how a customer moves from an existing tool or process to yours, including what to prepare, what carries over, how much work it is and how to reverse it. It is not a comparison page, and it works best when it does not argue against anyone.

This post is about the writing. For the wider rewrite of a feature page around a buying decision, see Rewrite a feature page around the decision it helps buyers make.

Where do you find the real switching objections?

Start with the objections engines raise when asked, then add what your own team hears. A switching objection is a reason a buyer gives for not moving from what they use today, such as "we would lose our history" or "it would take a quarter to retrain everyone".

The Objections screen in DiscoveredBy is one source, on plans that include it (see plans and limits). It runs a weekly objection study: every chat engine on your plan, plus ChatGPT (app), is asked one fixed question about your brand and each active tracked competitor (up to your plan's competitor allowance), namely what objections or reasons a buyer might have for not choosing it. An AI model reads the objections out of each answer and groups them by meaning, and each group shows how prominent it was across the engines that answered, how many engines raised it, and the quotes behind it. See how Objections works for the full method.

Two limits matter here. First, the question is designed to produce downsides, so almost every brand will have some; compare objections with each other, not as a verdict on your reputation. Second, the fixed question is about not choosing a brand in general. It does not ask about switching, so it will not hand you a list of migration worries. What it can do is show whether groups about setup effort, lost data or lock-in appear about you, and whether the "also raised about" count suggests they apply to your whole category or only to you.

Enlarge image

Combine that with three internal sources:

• Sales call notes and lost-deal reasons that mention risk or effort.
• Support tickets from customers in their first month.
• Questions your implementation team asks in every kickoff.

Where the sources agree, you have a section. Where only one mentions it, you have a candidate to test.

What should the four sections cover?

Each section answers one family of worries. Open each with a direct answer, then give the detail, the limit and the evidence.

Preparation: what does a buyer need before they start?

Tell them exactly what to gather, who needs to be involved and what must be true before day one. This is the section that turns a vague worry into a checklist. Cover access and permissions, the inventory of what they currently hold, decisions they must make in advance (what to keep, archive or drop), and any period when both tools will run side by side.

State prerequisites as facts, not marketing. If a step needs an administrator on the buyer's side, say so.

Data portability: what comes with them, and in what form?

Say which data types move, in which formats, and which do not. Losing history is a common worry, so this section should be the most specific on the page.

List each data type in a table: what it is, whether it moves, the accepted format, what is lost or changed, and how the buyer can check the result. Include the awkward rows. A page that says "everything migrates seamlessly" reads as a claim, while a page that names what does not migrate reads as evidence.

Portability also runs the other way. Say how a customer gets their data out of your product, because a buyer who can see the exit is less afraid of the entrance.

Implementation effort: how long, how much work, whose work?

Give the effort in terms of tasks and roles, and give time only where you can defend it. A range you cannot support is worse than none. Break the move into phases, name who does each one (the buyer, your team, or both), and say what can go wrong in each. If timing depends on volume, say what it depends on rather than quoting a single figure.

Be equally clear about what your team does not do. If training, data cleaning or integration work is the buyer's responsibility, name it.

Rollback: what happens if it goes wrong?

Explain what a buyer can undo, up to what point, and what it costs. Rollback is a section many guides skip, and it may be the one that decides whether a cautious buyer proceeds. Describe the point after which reversing becomes hard, whether the old tool can stay in use during a trial period, and what the buyer keeps if they leave.

Do not promise more than your product and contract provide. If some steps cannot be reversed, say which.

The deliverable: a migration guide outline

Copy this outline and replace the bracketed prompts. Every section ends with a "limits" line so that the honest constraints are written down rather than discovered later.

MIGRATION GUIDE OUTLINE

Title: Moving from [your current tool or process] to [Product]
Opening answer (80 to 120 words): who this guide is for, what the move
involves, the main effort in plain terms, and where to go if it fails.

1. Before you start (preparation)
   - Who should be involved: [roles]
   - What to gather: [list]
   - Decisions to make first: [keep / archive / drop]
   - Can both tools run at once? [yes / no / for how long]
   - Limits: [what must be true, what we cannot check for you]

2. What moves and what does not (data portability)
   Table columns: Data type | Moves? | Format accepted | What changes
   | How to verify
   - How to export from [Product] later: [steps or link]
   - Limits: [known gaps, lossy conversions]

3. How much work is it (implementation effort)
   - Phase 1 [name]: who does it, what is produced, common snag
   - Phase 2 [name]: ...
   - What affects duration: [drivers, not a single promise]
   - What is not included: [training, cleanup, integrations]
   - Limits: [what varies by customer]

4. If you need to go back (rollback)
   - What can be reversed and until when: [point of no return]
   - What you keep if you leave: [data, access, records]
   - Trial or parallel-run options: [only if they exist]
   - Limits: [steps that cannot be undone]

5. Frequently asked questions (4 to 6 real switching questions)

6. Evidence and dates
   - Where each claim is documented: [help page, contract term, product page]
   - Last reviewed: [date]   Reviewed by: [role]

7. Next step: one action (talk to the team, read the setup docs)

PRE-PUBLISH CHECKS
   - No other vendor is named or compared
   - No number appears that we cannot support
   - Every "moves / does not move" row was tested by someone on the team
   - The rollback section matches the contract and product behaviour
   - Someone outside the team can follow section 1 without help

Enlarge image

How do you turn objections into sections?

Map every objection group to the section that answers it, and check that no group is left without an answer. This makes the guide traceable: each paragraph exists because a real worry does.

Use a table like this one and keep it beside the draft.

If an objection has no evidence you can point to, do not write a reassuring sentence. Either find the evidence, or turn the answer into an honest limit.

Enlarge image

Illustrative example: Quillstone

Illustrative example: Quillstone and its competitors are fictional, and the numbers are made up to show the method.

Quillstone sells document-review software to mid-sized legal and compliance teams. Its team wants a guide for buyers moving from "Brieflane", a fictional competitor, though the guide itself will only say "your current review tool".

An objection study returns three groups for Quillstone, over three engines that answered. Prominence is the average of each engine's score for the group, where an engine that did not raise it counts as 0.

The arithmetic: (100 + 80 + 0) ÷ 3 = 60.0; (90 + 0 + 0) ÷ 3 = 30.0; (70 + 60 + 50) ÷ 3 = 60.0.

The team reads the quotes and adds its own notes. Sales says two lost deals mentioned "we cannot pause reviews during a move". Support says new customers often ask whether the old tool can stay open. The mapping:

The "also raised about" column changes the writing. Review history is raised about both competitors, so it is a category worry: Quillstone can address it without implying it is uniquely at fault. Data on exit is raised about Quillstone only, so it needs a prominent, specific answer.

Quillstone does not write "migration takes two weeks". It has no tested figure, so the guide says timing depends on the volume of history and the number of reviewers, and lists those drivers. Where a conversion is lossy, the portability table says so.

How do you turn the outline into a draft?

Use the objection map to brief a writer, and keep the evidence step in human hands. DiscoveredBy's Articles feature can help with the first part. You can start a topic from a citation gap or type your own title. The brief decides which asset to build, from updating a page you own to publishing something new to holding off, and only a brand new article or comparison page is drafted. On plans that ground drafts in source pages, when the brief calls for a new page and needs proof only you have, such as pricing or customer proof it cannot invent, generation can pause at "Needs your input" and list it under "Proof only you have". Every claim the writer reports carries one of six labels, and a claim earns "verified by source" only if its quoted evidence passes a check against the source page it names. Nothing is published for you; see how Articles works. Drafts can be sent to WordPress as a new draft post on plans that include it (see WordPress drafts).

Two cautions. That claim check looks at the claims the writer lists, not every sentence, so a factual statement in the prose that was never listed is not checked. And it checks a claim against the pages the writer read, not against how your product behaves: whether "your history is exported as CSV" is true is a fact only your team can confirm.

Neighbouring pages can carry part of the load. A pricing page and support documentation each answer some switching questions; see Audit your pricing page for the questions AI buyers ask and Use support documentation to answer pre-purchase questions. To start from a citation gap, read Turn an AI citation gap into a content brief your writer can use.

Common mistakes and what this cannot tell you

• Promising a timeline you have not measured. A single confident duration can cost you trust when the first customer takes longer.
• Hiding the losses. A table where every row says "moves" invites a buyer to test the one row you skipped.
• Naming or attacking the other vendor. The guide should be useful to someone leaving any tool. Comparison belongs elsewhere, and it is outside this post.
• Skipping rollback. Its absence reads as an answer.
• Treating the study as a migration survey. The question it asks is general, and prominence is relative.
• Expecting AI engines to quote the guide. Suggested edits are hypotheses. Nothing here establishes that a migration guide raises citations or mentions; re-run the study and your tracked prompts over time and read changes cautiously.

Stated objections in an answer are an observation of that answer. They do not reveal why the engine produced it.

Frequently asked questions

Should a migration guide be public or only for customers?

Publish the parts a buyer needs before they sign: preparation, what moves, the shape of the effort and the rollback options. Keep account-specific steps and confidential material inside the customer area, and link to them from the public page.

Can I mention the tool my customers are leaving?

You can describe the move from "your current tool" without naming anyone. If you name a specific product, you take on the burden of describing it accurately, which is why this guide avoids it.

How long should a migration guide be?

Long enough to answer each section's questions with a fact, a limit and evidence. The outline above usually fills one substantial page; split it into separate pages only when audiences need different steps.

How often should I review it?

Whenever formats, limits or the rollback terms change, and on a set schedule otherwise. Record the review date and the reviewer on the page so a reader can judge how current it is.

How do I know if the guide is working?

Watch signals you can defend: whether switching questions in sales calls drop, and whether objection groups about setup or data change in later studies. Studies are compared only with earlier ones that asked the same question version in the same language, and a change is not proof that the guide caused it.

Next step

Open the latest objection study for your project (studies run weekly, and owners and editors can also run one on demand), read the quotes under any group about effort, data or lock-in, and fill in the mapping table before you draft. You can start at app.discoveredby.ai. For the wider view of how engines describe your brand, see Brand perception.