Writing a Switching Guide That Respects Readers

Moving from one product to another is a small project with real risks. Data might not transfer. People might not adapt. Something that worked in the old tool might not exist in the new one. A good switching guide treats that seriously. It acknowledges what the reader is risking and walks them through the move with care.

A bad one is a sales page in disguise: a list of reasons the old product is terrible, a button to sign up and a vague promise that everything will work. This article explains how to write the first kind.

Why switching guides exist

People who consider switching face several kinds of cost. Wikipedia lists them: uncertainty about whether performance will be worse, the effort of searching and evaluating options, the cost of setting up the new product, the loss of what has already been invested in the old one, the emotional discomfort of leaving something familiar and, in some markets, the collective effects of everyone else using the same tool.

A switching guide reduces several of those at once. It lowers uncertainty by describing what will happen. It lowers setup cost by providing steps. It lowers search cost by collecting information in one place. Done honestly, it is a gift to readers. Done dishonestly, it is a trap.

Start by knowing the reader

Before writing, decide who the guide is for and what they want.

• Which product are they leaving? Name it, factually.
• Why are they leaving? Price, features, trust, change of circumstances? A guide can acknowledge the common reasons without assuming everyone shares them.
• How technical are they? A guide for a solo freelancer differs from one for an IT department.
• What is at stake? A personal note app and a company's customer records carry different risks.
• How much time do they have? An afternoon, a week, a quarter?

Write one guide for one kind of reader. Several short guides serve better than one that tries to cover everyone.

The structure of a good switching guide

A reliable outline:

1. A short summary

What the guide covers, who it is for, how long it takes and what you will need. A reader should know in thirty seconds whether to continue.

2. Before you start: decide and prepare

• Check that the new product fits. A short list of must-haves, with honest notes about gaps.
• Back up everything from the old product. Say how.
• Check your rights and options for exporting data. Where personal data is involved, individuals have a right to data portability under UK data protection law, which the ICO describes as the ability to obtain and reuse personal data across different services in structured, commonly used, machine-readable formats, applying to data provided by the individual where processing is based on consent or contract and carried out by automated means. Mention this where relevant, and do not give legal advice.
• Note your settings and workflows in the old tool, so you can rebuild them.
• Tell the people affected, and agree a date.

3. What moves across, and what does not

A clear table of data types and what happens to each: fully imported, partly imported, must be recreated, not supported. This is the most valuable part of the guide, and the one most often missing. Be specific and honest. If comments will be lost, say so. If dates may shift, say so.

4. The steps

Numbered, specific, tested. Each step says what to do, where to click or what to run, what you should see and what to do if you do not see it. Use screenshots where they help, with alternative text.

5. Check the result

How to verify that the move worked: counts of items, spot checks of key records, a test of the main workflow. Give a short checklist.

6. Run in parallel, then retire the old one

Advise keeping the old product available for a period, so people can check and nothing is lost. Say when and how to cancel the old subscription, and warn about any deadlines or data deletion on the other side.

7. Common problems

A short list of issues people hit, with fixes. This comes from support experience.

8. Getting help

How to contact support, where the documentation is and what information to include in a request.

Be balanced

The temptation in a switching guide is to run down the old product. Resist it.

• Describe the old product fairly. Readers using it may like parts of it. Disparagement makes them defensive.
• State honest differences. "The new product does not have X. If you rely on X, you may want to wait." That is helpful, and it is respectful.
• Do not exaggerate benefits. A promise that is not kept costs you trust.
• Acknowledge that switching may not be right for everyone. A short "who should not switch" section is a mark of confidence.

Google's guidance on helpful content stresses original, people-first information and warns against content created primarily to attract visits. A switching guide that is balanced and genuinely useful meets the first test and passes the second.

Be accurate, and show your work

• Test every step on a clean account, ideally with someone who has not used the product before.
• Date the guide and note the product versions it covers.
• State what you tested and how. "Tested with a sample of two thousand contacts."
• Link to official documentation for both products.
• Correct errors openly with a dated note.

If you have not done the migration yourself, say that and describe what you based the guide on. Better still, do it.

Consider the data carefully

Data is where switching goes wrong.

• Formats. Which export formats does the old product offer? Which import formats does the new one accept? Describe any conversion.
• Limits. File sizes, record counts and rate limits.
• Integrity. How to check that nothing has been lost or altered.
• Privacy. Warn readers to handle exported files securely, since they may contain personal or confidential data. Delete temporary copies when done.
• Retention. Explain what happens to data in the old product after cancellation, and how long it remains available.

Do not ask readers to do anything risky without a warning and a backup step.

Respect people's time and attention

Keep the guide as short as is honest. Use plain words and clear headings. Put the most important warnings at the point where they matter, not in a distant footnote. Avoid pop-ups and interruptions that distract from a task that already needs care.

Add alternative text to images, ensure good contrast and make sure the guide works on a phone, since people often follow steps on one screen while working on another.

Do not make leaving the old product difficult

If you are the maker of the product they are leaving, be especially careful. Providing a clear export and honest guidance for people who wish to go elsewhere is a sign of integrity and, in the long run, good for trust. If you are the maker of the new product, do not hide the old product's export features or misrepresent them.

A worked example

A company that makes a simple task manager publishes a guide titled "Moving from a popular task tool to ours". It opens with a summary: "This guide takes about forty minutes for a personal account with up to a few hundred tasks. You will need an export from your old account and a free account with us."

The "before you start" section lists three must-haves, such as recurring tasks and file attachments, and says plainly which are supported: recurring tasks are, file attachments are not yet. A table shows what imports: task titles, due dates and notes move across; labels become tags; comments and attachments do not; recurring rules are imported but may need checking.

Eleven numbered steps follow, each tested on a fresh account, with screenshots. A "check the result" section asks readers to compare task counts and open five tasks with due dates. The guide recommends keeping the old account for thirty days. It ends with a "who should not switch" paragraph: "If you rely on file attachments or shared team projects, our product is not ready for you yet." The guide is dated and notes the versions tested. Readers comment that they appreciated the honesty, and the support team reports fewer confused emails.

A checklist

• Clear reader and purpose
• Summary at the top
• Preparation and backup
• Honest table of what moves and what does not
• Tested, numbered steps
• A way to verify the result
• Parallel running and a clean exit
• Common problems and help
• Balanced tone, no disparagement
• Dated, versioned and corrected openly
• Careful about data and privacy

On this site, the categories page shows tools by purpose and the search page finds listings by words, while the submit page lets makers add listings that can link to their own guides.

Frequently asked questions

Should I include a sign-up button? A discreet link at the end is fine. Do not make the guide a funnel.

What if the old product changes its export? Update the guide with a dated note, and test again.

Can I write a guide for a product I do not make? Yes, if you have used both. Say who you are and whether you have an interest.