website: v0.12 preview upgrade guide tweaks

Based on some feedback on the initial draft, make some minor updates to
how information is presented in the preview upgrade guide for v0.12.

This also includes some minor copy-editing work to try to make the "voice"
more consistent between different sections of the guide.

website/upgrade-guides/0-12.html.markdown

@@ -25,24 +25,33 @@ has its own upgrade guide, so please consult the other guides (available in the
 navigation) if you are upgrading directly from an earlier version.
 
 ## Upgrading Terraform configuration
+
 The majority of users will not need to make manual changes to their Terraform
 configurations to upgrade to 0.12. The users who will need to make manual
 changes are users who use language workarounds in previous Terraform versions.
 Examples of these workarounds include:
 
 - Treating block types like attributes in an attempt to work around Terraform
-not supporting generating nested blocks dynamically.
+  not supporting generating nested blocks dynamically.
+  ([#7034](https://github.com/hashicorp/terraform/issues/7034))
+
+- Wrapping redundant list brackets (`[` and `]`) around splat expressions in
+  order to force them to be interpreted as lists even when there are unknown
+  items in the list.
 
 Note that these workarounds are not "wrong", but rather clever solutions by
 dedicated community members! These folks have been the inspiration for HCL2 and
-their clever solutions have given guidance on how to make the Terraform language
+these solutions have given guidance on how to make the Terraform language
 more flexible to meet the needs of complex infrastructure.
 
+Terraform 0.12 will be released with a migration tool that will make most of
+the required updates automatically, and also provide guidance on any changes
+that require human input.
+
 For users who follow the examples in the Terraform documentation, there should
-be no required changes. While no manual changes are needed, users can still run
-the migration tool to convert to the more readable syntax supported in this
-release. For those users, Terraform 0.12 will be released with a migration tool
-to guide users through upgrading their configurations.
+be no required changes. However, we still recommend to run the migration tool
+to upgrade to the more readable syntax conventions supported in this release,
+and to draw attention to any potential issues.
 
 ## Upgrading Terraform providers
 
@@ -51,45 +60,45 @@ and schema transfer.
 
 In Terraform 0.12 Terraform will have an awareness of the schemas used by both
 provider and provisioner plugins. This V1 for the RPC plugin protocols will
-still use the old-style passing of map[string]interface{} for config and
-map[string]string with flatmap for state/diff.
+still use the old-style passing of `map[string]interface{}` for config and
+`map[string]string` with flatmap for state and diff.
 
-In order to ease the transition to the new version of terraform, backwards
-compatible providers will be built allowing them to be used with previous
-versions of terraform. Backwards compatibility through this mechanism is not a
-long term strategy for maintaining providers in the event of further protocol
-changes, and is only a stepping stone.
+To avoid the need to atomically upgrade both Terraform Core and the providers
+all at once, new provider versions will be released that are compatible with
+both v0.12 and prior versions. Users will need to upgrade to the new
+v0.12-compatible provider releases before upgrading Terraform Core, but can
+use these newer provider releases with prior Terraform versions to transition
+gradually and reduce risk.
 
-Having new providers be backwards compatible with older versions of Terraform
-alleviates provider developers from the responsibility of maintaining a branch
-for backports, allows any major version changes to be available to older
-clients, and reduces the urgency for users to upgrade everything at once.
+This compatibility support will be handled automatically by a new version of
+the plugin SDK so that provider maintainers need only to upgrade to the
+latest version and rebuild.
 
-To upgrade a provider to use the new RPC plugin protocol in 0.12 and remain
-backwards compatible with previous releases, providers will need to update their
-Terraform dependencies to a 0.12 release. The changes to the helper packages are
-being designed so that updating the packages will allow the provider to work
-with the new plugin protocol, while remaining compatible with previous Terraform
-releases.
+The dual-protocol compatibility will be retained at least until the next
+major release of the plugin SDK, in order to give users time to perform a
+gradual upgrade of each provider and of Terraform Core itself.
 
 ## Upgrading modules
-Module authors will need to complete several steps to get their modules 0.12
-ready.
 
-1. Follow the steps in "Upgrading Terraform configurations" to get the module
-code upgraded
-1. The migration tool will automatically add a >= 0.12.0 Terraform version pin.
-No action is needed, just awareness.
-1. Update provider version requirements if there are version pins in the module
-1. If you are using the Terraform Registry, publish a new major version of the
-module. If you are not using the registry, make sure downstream consumers of the
-module are aware of the update.
+Module authors will need to complete several steps to get their modules ready
+for v0.12.
+
+1. Follow the steps in "Upgrading Terraform configurations" above to get the
+   module code upgraded
+1. The migration tool will automatically add a `>= 0.12.0` Terraform version
+   constraint to indicate that the module has been upgraded to use v0.12-only
+   features.
+1. If the module is published in a module registry, publish a new major version
+   of the module to indicate that the new version is not compatible with older
+   versions of Terraform. If you are not using a registry, be sure that
+   downstream consumers of the module are aware of the update.
 
 Module consumers can then upgrade to the new versions of the module by upgrading
-their configurations to 0.12 and updating the module version in that
-configuration.
+their configurations to 0.12 and updating the module version constraint in each
+configuration to refer to the new major version.
 
 ## Upgrading Sentinel policies
+
 Terraform Enterprise users of Sentinel will need to complete the below steps to
 upgrade Sentinel to work with Terraform 0.12.
 
@@ -99,3 +108,5 @@ upgrade Sentinel to work with Terraform 0.12.
 Because Sentinel is applied across all workspaces in Terraform Enterprise, all
 workspaces must be upgraded to Terraform 0.12 otherwise Sentinel policies will
 fail on versions below 0.12.
+
+More details on this upgrade process will be added prior to the final release.