CRM Migration Runbook: What to Document Before You Switch Systems

A migration is more than moving records

When a team replaces an old tool, the visible task is often data migration. The harder task is discovering the operating model hidden inside fields, views, habits, permissions, and manual workarounds.

If the project copies the old tables without understanding the process, it can reproduce the same confusion in a new interface. Documentation helps the team separate the old tool’s shape from the work the organisation actually needs to perform.

Create a document set, not one giant file

A migration is easier to manage when each document has a clear purpose and audience.

• Project brief: why the migration exists, the target outcome, scope, assumptions, and constraints.
• Current-state map: entities, workflows, ownership, pain points, and dependencies.
• Target-state design: the new data model, views, permissions, and operating rules.
• Migration plan: mapping, cleanup, validation, coexistence, rollout, and handoff activities.
• Risk and issue register: hidden rules, data mismatch, adoption, access, and continuity risks.
• Status and close-out reports: what was delivered, what remains, and what the team learned.

Use coexistence as a control

A parallel period lets the team compare the new system with real work before making the switch irreversible. It creates a feedback loop for missing workflow states, confusing views, data gaps, and ownership questions.

Coexistence should have an exit condition. Define the scenarios the new system must support, the issues that must be resolved, and the person responsible for the final decision.

Document decisions and sanitise deliberately

Public case studies and internal handoff documents have different privacy boundaries. A public version can show the problem, architecture, controls, and outcomes without publishing client names, records, credentials, internal URLs, or production IDs.

The goal is not to hide the project. It is to expose the reasoning that a reviewer can safely evaluate.

The result is operational confidence

In my internal CRM migration case, the public documentation shows the process map, target model, coexistence approach, risk controls, SOPs, and handoff thinking. That is what makes the migration reviewable as a project-management outcome, not just as a technical build.