Overview
Set the purpose, scope, audience, and boundaries before the detailed chapters.
4.8
on G2
Free Downloadable Template
Plan, run, validate, and roll back a move between systems, platforms, or versions in migration-phase order. Download the editable blank, or create a draft from your recordings in Docsie.
Use this guide to plan a migration, control cutover, verify the target, and recover if the acceptance criteria are not met. Record the source and target versions and keep each migration wave traceable to its checks.
Complete the bracketed fields with approved information for the product, organization, or program being documented. Repeat the named forms where several tasks or subjects need separate records. Remove sections that do not apply and retain links to the material used to complete the document.
| Document control | Entry |
|---|---|
| Document identifier | [Identifier used by your team] |
| Scope and applicable version | [Product, program, locations, and version covered] |
| Prepared and maintained by | [Responsible role or team] |
| Revision and review | [Revision, review date, and approval reference] |
Define the migration boundary and the people affected. State the supported paths and distinguish a migration objective from the criteria used to accept its result.
| Field | Complete with |
|---|---|
| Source and target | [Systems, workloads, platforms, versions, and environments] |
| Purpose and scope | [Reason for the migration, included items, exclusions, and affected users] |
| Supported paths | [Direct path or required intermediate versions and their source references] |
| Responsibilities | [Decision authority, execution roles, application owners, and communication route] |
Repeat the change record for breaking changes, removed features, and changed defaults. Link each change to the action required by an affected user or integration.
| Field | Complete with |
|---|---|
| Change identifier | [Feature, setting, interface, or data behavior that changes] |
| Before and after | [Source behavior, target behavior, and applicable versions] |
| Impact and action | [Affected clients, data, users, and the change they must make] |
| Mapping and evidence | [Source-to-target mapping and authoritative compatibility reference] |
Plan waves around dependencies and verifiable outcomes. Keep go or no-go decisions, success criteria, and rollback criteria explicit.
| Field | Complete with |
|---|---|
| Strategy and waves | [Method, wave membership, sequence, dependencies, and rationale] |
| Window and communications | [Approved timing or downtime, notices, and responsible roles] |
| Decision points | [Readiness, cutover, and acceptance decisions with required evidence] |
| Recovery plan | [Rollback triggers, decision authority, recovery path, and verified source state] |
Complete discovery and preparation before moving data or changing traffic. Keep the backup, target configuration, and readiness results linked to the wave they protect.
| Field | Complete with |
|---|---|
| Discovery | [Inventory, compatibility assessment, dependencies, and unresolved issues] |
| Backup and recovery | [Protected data and configuration, backup reference, and restore verification] |
| Target readiness | [Provisioning, access, connectivity, configuration, and capacity checks] |
| Freeze and authorization | [Change freeze scope, final synchronization plan, and readiness approval] |
Repeat this procedure for each supported task or variant. Place the applicable warning before the affected action and record a result that can be checked.
| Step | Action | Expected result | Evidence |
|---|---|---|---|
| 1 | [One action using the exact interface label or approved command] | [Observable state] | [Check or record] |
| 2 | [Next action in dependency order] | [Observable state] | [Check or record] |
| 3 | [Verification or handover action] | [Completion condition] | [Retained evidence] |
Repeat this procedure for each component or wave. Record progress checkpoints so an interrupted move can be reconciled before it is resumed.
| Field | Complete with |
|---|---|
| Wave and starting state | [Items, source checkpoint, target readiness, and required authority] |
| Execution | [Transfer, transformation, synchronization, and traffic or user switch sequence] |
| Progress record | [Checkpoint, completed item, exception, timestamp, and evidence] |
| Failure response | [Stop condition, partial-state reconciliation, and recovery decision] |
Repeat this procedure for each supported task or variant. Place the applicable warning before the affected action and record a result that can be checked.
| Step | Action | Expected result | Evidence |
|---|---|---|---|
| 1 | [One action using the exact interface label or approved command] | [Observable state] | [Check or record] |
| 2 | [Next action in dependency order] | [Observable state] | [Check or record] |
| 3 | [Verification or handover action] | [Completion condition] | [Retained evidence] |
Verify data and functionality separately. Record counts, relationships, and user outcomes using criteria defined before migration.
| Field | Complete with |
|---|---|
| Data integrity | [Object counts, checksums, relationships, transformed fields, and comparison method] |
| Functional checks | [Critical workflow, test input, expected outcome, and observed result] |
| Operational checks | [Access, monitoring, integrations, performance measures, and support readiness] |
| Acceptance decision | [Unresolved discrepancy, accepted exception, decision role, and evidence] |
Document how the source state can be restored and how changes made after cutover are handled. Use only the recovery path approved for this migration.
| Field | Complete with |
|---|---|
| Trigger and authority | [Conditions requiring rollback and the role that decides] |
| Protected state | [Backup or checkpoint, dependencies, and expected restored state] |
| Reversal sequence | [Traffic, application, data, and configuration reversal actions] |
| Verification and communication | [Checks confirming recovery, affected users, and closure record] |
Repeat this procedure for each supported task or variant. Place the applicable warning before the affected action and record a result that can be checked.
| Step | Action | Expected result | Evidence |
|---|---|---|---|
| 1 | [One action using the exact interface label or approved command] | [Observable state] | [Check or record] |
| 2 | [Next action in dependency order] | [Observable state] | [Check or record] |
| 3 | [Verification or handover action] | [Completion condition] | [Retained evidence] |
Record the work that makes the target sustainable after acceptance. Keep source decommissioning separate from the initial cutover decision.
| Field | Complete with |
|---|---|
| Stabilization | [Monitoring focus, observed issues, responsible role, and review point] |
| Dependent changes | [Integrations, client settings, documents, and operating procedures to update] |
| Source retirement | [Retention, archive, access removal, decommissioning approval, and evidence] |
| Handover | [Support ownership, training, remaining actions, and completion record] |
Repeat this record for each migration symptom or known incompatibility. Link corrective actions to the affected wave or component.
| Field | Complete with |
|---|---|
| Symptom | [Exact error or discrepancy and the phase where it appears] |
| Diagnosis | [Checks, evidence, likely causes, and relevant migration checkpoint] |
| Resolution | [Approved corrective action, resumption point, and validation] |
| Escalation | [Decision trigger, responsible role, and evidence required] |
Keep values and mappings used by several procedures in one place. State the version and environment to which each reference applies.
| Field | Complete with |
|---|---|
| Compatibility | [Source and target version matrix and supported intermediate paths] |
| Settings and commands | [Exact values, units, syntax, purpose, and source reference] |
| Mappings | [Legacy identifier or field, target equivalent, and transformation rule] |
| Terminology and records | [Terms, retained evidence locations, and change history] |
8 Repeatable Chapter Patterns
Teams preparing a migration guide from existing source material. Repeat a procedure, checklist, or reference chapter where needed, and keep only the sections your source material supports.
Set the purpose, scope, audience, and boundaries before the detailed chapters.
Identify affected users or integrations, the changes they face, and the supported transition path.
Describe the starting and target states, dependencies, migration sequence, verification, and recovery.
Give each task its prerequisites, ordered actions, expected result, and verification.
Use repeatable checks for readiness, handover, or completion.
Keep exact settings, field values, commands, and supporting references easy to look up.
Connect an observable symptom to diagnostic checks, resolution, and verification.
Group recurring questions with clear, source-supported answers and useful references.
Use this guide to plan a migration, control cutover, verify the target, and recover if the acceptance criteria are not met. Record the source and target versions and keep each migration wave traceable to its checks.
Complete the bracketed fields with approved information for the product, organization, or program being documented. Repeat the named forms where several tasks or subjects need separate records. Remove sections that do not apply and retain links to the material used to complete the document.
| Document control | Entry |
|---|---|
| Document identifier | [Identifier used by your team] |
| Scope and applicable version | [Product, program, locations, and version covered] |
| Prepared and maintained by | [Responsible role or team] |
| Revision and review | [Revision, review date, and approval reference] |
Define the migration boundary and the people affected. State the supported paths and distinguish a migration objective from the criteria used to accept its result.
| Field | Complete with |
|---|---|
| Source and target | [Systems, workloads, platforms, versions, and environments] |
| Purpose and scope | [Reason for the migration, included items, exclusions, and affected users] |
| Supported paths | [Direct path or required intermediate versions and their source references] |
| Responsibilities | [Decision authority, execution roles, application owners, and communication route] |
Repeat the change record for breaking changes, removed features, and changed defaults. Link each change to the action required by an affected user or integration.
| Field | Complete with |
|---|---|
| Change identifier | [Feature, setting, interface, or data behavior that changes] |
| Before and after | [Source behavior, target behavior, and applicable versions] |
| Impact and action | [Affected clients, data, users, and the change they must make] |
| Mapping and evidence | [Source-to-target mapping and authoritative compatibility reference] |
Plan waves around dependencies and verifiable outcomes. Keep go or no-go decisions, success criteria, and rollback criteria explicit.
| Field | Complete with |
|---|---|
| Strategy and waves | [Method, wave membership, sequence, dependencies, and rationale] |
| Window and communications | [Approved timing or downtime, notices, and responsible roles] |
| Decision points | [Readiness, cutover, and acceptance decisions with required evidence] |
| Recovery plan | [Rollback triggers, decision authority, recovery path, and verified source state] |
Complete discovery and preparation before moving data or changing traffic. Keep the backup, target configuration, and readiness results linked to the wave they protect.
| Field | Complete with |
|---|---|
| Discovery | [Inventory, compatibility assessment, dependencies, and unresolved issues] |
| Backup and recovery | [Protected data and configuration, backup reference, and restore verification] |
| Target readiness | [Provisioning, access, connectivity, configuration, and capacity checks] |
| Freeze and authorization | [Change freeze scope, final synchronization plan, and readiness approval] |
Repeat this procedure for each supported task or variant. Place the applicable warning before the affected action and record a result that can be checked.
| Step | Action | Expected result | Evidence |
|---|---|---|---|
| 1 | [One action using the exact interface label or approved command] | [Observable state] | [Check or record] |
| 2 | [Next action in dependency order] | [Observable state] | [Check or record] |
| 3 | [Verification or handover action] | [Completion condition] | [Retained evidence] |
Repeat this procedure for each component or wave. Record progress checkpoints so an interrupted move can be reconciled before it is resumed.
| Field | Complete with |
|---|---|
| Wave and starting state | [Items, source checkpoint, target readiness, and required authority] |
| Execution | [Transfer, transformation, synchronization, and traffic or user switch sequence] |
| Progress record | [Checkpoint, completed item, exception, timestamp, and evidence] |
| Failure response | [Stop condition, partial-state reconciliation, and recovery decision] |
Repeat this procedure for each supported task or variant. Place the applicable warning before the affected action and record a result that can be checked.
| Step | Action | Expected result | Evidence |
|---|---|---|---|
| 1 | [One action using the exact interface label or approved command] | [Observable state] | [Check or record] |
| 2 | [Next action in dependency order] | [Observable state] | [Check or record] |
| 3 | [Verification or handover action] | [Completion condition] | [Retained evidence] |
Verify data and functionality separately. Record counts, relationships, and user outcomes using criteria defined before migration.
| Field | Complete with |
|---|---|
| Data integrity | [Object counts, checksums, relationships, transformed fields, and comparison method] |
| Functional checks | [Critical workflow, test input, expected outcome, and observed result] |
| Operational checks | [Access, monitoring, integrations, performance measures, and support readiness] |
| Acceptance decision | [Unresolved discrepancy, accepted exception, decision role, and evidence] |
Document how the source state can be restored and how changes made after cutover are handled. Use only the recovery path approved for this migration.
| Field | Complete with |
|---|---|
| Trigger and authority | [Conditions requiring rollback and the role that decides] |
| Protected state | [Backup or checkpoint, dependencies, and expected restored state] |
| Reversal sequence | [Traffic, application, data, and configuration reversal actions] |
| Verification and communication | [Checks confirming recovery, affected users, and closure record] |
Repeat this procedure for each supported task or variant. Place the applicable warning before the affected action and record a result that can be checked.
| Step | Action | Expected result | Evidence |
|---|---|---|---|
| 1 | [One action using the exact interface label or approved command] | [Observable state] | [Check or record] |
| 2 | [Next action in dependency order] | [Observable state] | [Check or record] |
| 3 | [Verification or handover action] | [Completion condition] | [Retained evidence] |
Record the work that makes the target sustainable after acceptance. Keep source decommissioning separate from the initial cutover decision.
| Field | Complete with |
|---|---|
| Stabilization | [Monitoring focus, observed issues, responsible role, and review point] |
| Dependent changes | [Integrations, client settings, documents, and operating procedures to update] |
| Source retirement | [Retention, archive, access removal, decommissioning approval, and evidence] |
| Handover | [Support ownership, training, remaining actions, and completion record] |
Repeat this record for each migration symptom or known incompatibility. Link corrective actions to the affected wave or component.
| Field | Complete with |
|---|---|
| Symptom | [Exact error or discrepancy and the phase where it appears] |
| Diagnosis | [Checks, evidence, likely causes, and relevant migration checkpoint] |
| Resolution | [Approved corrective action, resumption point, and validation] |
| Escalation | [Decision trigger, responsible role, and evidence required] |
Keep values and mappings used by several procedures in one place. State the version and environment to which each reference applies.
| Field | Complete with |
|---|---|
| Compatibility | [Source and target version matrix and supported intermediate paths] |
| Settings and commands | [Exact values, units, syntax, purpose, and source reference] |
| Mappings | [Legacy identifier or field, target equivalent, and transformation rule] |
| Terminology and records | [Terms, retained evidence locations, and change history] |
Bring your recordings and select this template. Docsie organizes supported material into chapters and task articles for your team to review.
Downloads are editable blank templates. Review generated content against your source material before use.
Install, configure, secure, monitor, back up, and maintain a system as its administrator
Software architecture description in arc42 order: goals, context, views, decisions, quality, and risks
Developer portal with quickstart, authentication, concepts, how-to guides, endpoint reference, errors, and changelog.