doc: Updates table formatting and migration guides

docs/guides/advanced-cluster-preview-provider-v2.md

@@ -124,7 +124,8 @@ tags = {
 ## Best Practices Before Migrating
 Before doing any migration create a backup of your [Terraform state file](https://developer.hashicorp.com/terraform/cli/commands/state).
 
-## How to migrate
+## How to migrate `mongodbatlas_advanced_cluster` to Preview for MongoDB Atlas Provider v2 
+
 The process to migrate from current `mongodbatlas_advanced_cluster` to the one in Preview for MongoDB Atlas Provider v2 is as follows:
 - Before starting, run `terraform plan` to make sure that there are no planned changes.
 - Set environment variable `MONGODB_ATLAS_PREVIEW_PROVIDER_V2_ADVANCED_CLUSTER=true` in order to use the Preview for MongoDB Atlas Provider v2. You can also define the environment variable in your local development environment so your tools can use the new format and help you with linting and auto-completion.

docs/guides/cluster-to-advanced-cluster-migration-guide.md

@@ -6,11 +6,6 @@ page_title: "Migration Guide: Cluster to Advanced Cluster"
 
 **Objective**: This guide explains how to replace the `mongodbatlas_cluster` resource with the `mongodbatlas_advanced_cluster` resource. The data source(s) migration only requires [output changes](#output-changes) as data sources only read clusters.
 
-**Note**: Please look at the section [Moved block](#moved-block) below for an improved migration path. We are also exploring additional migration paths. If interested to learn more or to test out directly please contact [email protected].
-
-## Best Practices Before Migrating
-Before doing any migration create a backup of your [Terraform state file](https://developer.hashicorp.com/terraform/cli/commands/state).
-
 ## Main Changes Between `mongodbatlas_cluster` and `mongodbatlas_advanced_cluster`
 
 1. Replication Spec Configuration: Supports different node types (electable, analytics, read_only) where hardware configuration can differ between node types. `regions_config` is renamed to `region_configs`.
@@ -90,11 +85,46 @@ resource "mongodbatlas_advanced_cluster" "this" {
   - Before: It was deprecated.
   - After: Use `mongodbatlas_cloud_backup_schedule` resource instead.
 
+## Best Practices Before Migrating
+
+Before doing any migration create a backup of your [Terraform state file](https://developer.hashicorp.com/terraform/cli/commands/state).
+
+## Migration using Moved block (recommended)
+
+The [moved block](https://developer.hashicorp.com/terraform/language/moved) is a Terraform feature that allows to move between resource types. It's conceptually similar to do `removed` and `import` but it's more convenient as it's done in one step, and can be used in `modules`. This is our recommended method to migrate from `mongodbatlas_cluster` to `mongodbatlas_advanced_cluster`.
+
+ The main requirements are:
+ - Terraform version 1.8 or later is required, more info in the [State Move doc](https://developer.hashicorp.com/terraform/plugin/framework/resources/state-move).
+ -  Preview for MongoDB Atlas Provider v2 of `mongodbatlas_advanced_cluster` is required, you can find more info in the [resource doc](../resources/advanced_cluster%2520%2528preview%2520provider%2520v2%2529) and the [Migration Guide: Advanced Cluster Preview Provider v2](advanced-cluster-preview-provider-v2).
+
+The process to migrate from `mongodbatlas_cluster` to `mongodbatlas_advanced_cluster` using the `moved` block is as follows:
+- Before starting, run `terraform plan` to make sure that there are no planned changes.
+- Add the `mongodbatlas_advanced_cluster` resource definition. 
+  - Make sure environment variable `MONGODB_ATLAS_PREVIEW_PROVIDER_V2_ADVANCED_CLUSTER=true` is set in order to use the Preview for MongoDB Atlas Provider v2. You can also define the environment variable in your local development environment so your tools can use the new format and help you with linting and auto-completion.
+  - The [Atlas CLI plugin](https://github.com/mongodb-labs/atlas-cli-plugin-terraform) can be used to generate the `mongodbatlas_advanced_cluster` resource definition. This is the recommended method as it will generate a clean configuration keeping the original Terraform expressions.
+  - Alternatively, you can use the `terraform plan -generate-config-out=adv_cluster.tf` method to create the `mongodbatlas_advanced_cluster` resource definition, or create it manually.
+- Comment out or delete the `mongodbatlas_cluster` resource definition.
+- Add the `moved` block to your configuration file, e.g.:
+```terraform
+moved {
+  from = mongodbatlas_cluster.this
+  to   = mongodbatlas_advanced_cluster.this
+}
+```
+- Run `terraform plan` and make sure that there are no planned changes, only the moved should be shown. **Important**: Don't apply until planning shows only the moved changes. If it shows other changes, you will need to keep updating the `mongodb_atlas_advanced_cluster` configuration until it matches the original `mongodbatlas_cluster` configuration.
+- Run `terraform apply` to apply the changes. The `mongodbatlas_cluster` resource will be removed from the Terraform state and the `mongodbatlas_advanced_cluster` resource will be added.
+- At this moment you can delete the `moved` block from your configuration file, although it's recommended to keep it to help track the migrations.
+
+You can find full-detailed examples in [migrate_cluster_to_advanced_cluster](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_cluster_to_advanced_cluster).
+
 ## Migration using `terraform plan -generate-config-out=adv_cluster.tf`
+
 This method uses only [Terraform native tools](https://developer.hashicorp.com/terraform/language/import/generating-configuration) and is ideal if you:
 1. Have an existing cluster without any Terraform configuration and want to manage your cluster with Terraform.
 2. Have existing `mongodbatlas_cluster` resource(s) and don't want to use an external script for migrating.
 
+**Note**: We recommend the `moved block` method as it's more convenient and less error-prone. If you continue with this method, you should still use the Preview for MongoDB Atlas Provider v2 by setting the environment variable `MONGODB_ATLAS_PREVIEW_PROVIDER_V2_ADVANCED_CLUSTER=true` to avoid having to migrate again in the future.
+
 ### Procedure
 
 1. Find the import IDs of the clusters you want to migrate: `{PROJECT_ID}-{CLUSTER_NAME}`, such as `664619d870c247237f4b86a6-legacy-cluster`
@@ -187,29 +217,3 @@ This method uses only [Terraform native tools](https://developer.hashicorp.com/t
 
 ### Terraform Actions
 Using the `project_id` and `cluster.name`, Terraform imports your cluster and uses the new `mongodbatlas_advanced_cluster` schema to generate a configuration file. This file includes all configurable values in the schema, but none of the previous configuration defined for your `mongodbatlas_cluster`. Therefore, the new configuration will likely be a lot more verbose and contain none of your original [Terraform expressions.](https://developer.hashicorp.com/terraform/language/expressions)
-
-## Moved block
-
-The [moved block](https://developer.hashicorp.com/terraform/language/moved) is a Terraform feature that allows to move between resource types. It's conceptually similar to do `removed` and `import` but it's more convenient as it's done in one step, and can be used in `modules`. The main requirements are:
- - Terraform version 1.8 or later is required, more info in the [State Move doc](https://developer.hashicorp.com/terraform/plugin/framework/resources/state-move).
- -  Preview for MongoDB Atlas Provider v2 of `mongodbatlas_advanced_cluster` is required, you can find more info in the [resource doc](../resources/advanced_cluster%2520%2528preview%2520provider%2520v2%2529) and the [Migration Guide: Advanced Cluster Preview Provider v2](advanced-cluster-preview-provider-v2).
-
-The process to migrate from `mongodbatlas_cluster` to `mongodbatlas_advanced_cluster` using the `moved` block is as follows:
-- Before starting, run `terraform plan` to make sure that there are no planned changes.
-- Add the `mongodbatlas_advanced_cluster` resource definition. 
-  - Make sure environment variable `MONGODB_ATLAS_PREVIEW_PROVIDER_V2_ADVANCED_CLUSTER=true` is set in order to use the Preview for MongoDB Atlas Provider v2. You can also define the environment variable in your local development environment so your tools can use the new format and help you with linting and auto-completion.
-  - The [Atlas CLI plugin](https://github.com/mongodb-labs/atlas-cli-plugin-terraform) can be used to generate the `mongodbatlas_advanced_cluster` resource definition. This is the recommended method as it will generate a clean configuration keeping the original Terraform expressions.
-  - Alternatively, you can use the `terraform plan -generate-config-out=adv_cluster.tf` method to create the `mongodbatlas_advanced_cluster` resource definition, or create it manually.
-- Comment out or delete the `mongodbatlas_cluster` resource definition.
-- Add the `moved` block to your configuration file, e.g.:
-```terraform
-moved {
-  from = mongodbatlas_cluster.this
-  to   = mongodbatlas_advanced_cluster.this
-}
-```
-- Run `terraform plan` and make sure that there are no planned changes, only the moved should be shown. **Important**: Don't apply until planning shows only the moved changes. If it shows other changes, you will need to keep updating the `mongodb_atlas_advanced_cluster` configuration until it matches the original `mongodbatlas_cluster` configuration.
-- Run `terraform apply` to apply the changes. The `mongodbatlas_cluster` resource will be removed from the Terraform state and the `mongodbatlas_advanced_cluster` resource will be added.
-- At this moment you can delete the `moved` block from your configuration file, although it's recommended to keep it to help track the migrations.
-
-You can find full-detailed examples in [migrate_cluster_to_advanced_cluster](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_cluster_to_advanced_cluster).

examples/migrate_cluster_to_advanced_cluster/module_maintainer/README.md

@@ -4,7 +4,7 @@ The purpose of this example is to demonstrate how a Terraform module can help in
 The example contains three module versions which represent the three steps of the migration:
 
 Step | Purpose | Resources
---- | --- | --- | ---
+--- | --- | ---
 [Step 1](./v1) | Baseline | `mongodbatlas_cluster`
 [Step 2](./v2) | Migrate to advanced_cluster with no change in variables or plan | `mongodbatlas_advanced_cluster`
 [Step 3](./v3) | Use the latest features of advanced_cluster | `mongodbatlas_advanced_cluster`