Made permadiff page have a more general title and added more links to…

… it (#12124)

docs/content/develop/permadiff.md → docs/content/develop/diffs.md

@@ -1,15 +1,21 @@
 ---
-title: "Fix a permadiff"
+title: "Fix diffs"
 weight: 60
+aliases:
+  - /develop/permadiff
 ---
 
-# Fix a permadiff
+# Fix diffs
 
-Permadiffs are an extremely common class of errors that users experience. They manifest as diffs at plan time on fields that a user has not modified in their configuration. They can also show up as test failures with the error message: "After applying this test step, the plan was not empty."
+This page outlines best practices for fixing various kinds of diffs that can show up at plan time. These will often show up as test failures with the text: `After applying this test step, the plan was not empty.`. They can also show up for users at plan time, on fields that a user has not modified in their configuration. If the diff does not go away even after running `terraform apply` more than once with the same configuration, the diff is called a "permadiff".
 
-In a general sense, permadiffs are caused by the API returning a different value for the field than what the user sent, which causes Terraform to try to re-send the same request, which gets the same response, which continues to result in the user seeing a diff. In general, APIs that return exactly what the user sent are more friendly for Terraform or other declarative tooling. However, many GCP APIs normalize inputs, have server-side defaults that are returned to the user, do not return all the fields set on a resource, or return data in a different format in some other way.
+In a general sense, diffs appear when the API response is detected by Terraform to be different than what is in the user's configuration. This can happen for a number of reasons, including:
 
-This page outlines best practices for working around various types of permadiffs in the `google` and `google-beta` providers.
+- API returns a normalized version of the input
+- API returns server-side defaults if the field is unset
+- API does not return all the fields set on a resource (for example, secrets)
+
+The sections below describe in more detail how to address a number of different causes of diffs.
 
 ## API returns default value for unset field {#default}
 

docs/content/develop/field-reference.md

@@ -81,7 +81,7 @@ state. See
 for more information.
 
 Sensitive fields are often not returned by the API (because they are sensitive).
-In this case, the field will also need to use [`ignore_read` or a `custom_flatten` function]({{< ref "/develop/permadiff#ignore_read" >}}).
+In this case, the field will also need to use [`ignore_read` or a `custom_flatten` function]({{< ref "/develop/diffs#ignore_read" >}}).
 
 Example:
 
@@ -234,7 +234,7 @@ Example:
 Specifies the name of a [diff suppress function](https://developer.hashicorp.com/terraform/plugin/sdkv2/schemas/schema-behaviors#diffsuppressfunc)
 to use for this field. In many cases, a [custom flattener](https://googlecloudplatform.github.io/magic-modules/develop/custom-code/#custom_flatten)
 is preferred because it will allow the user to see a clearer diff when the field actually is being changed. See
-[Fix a permadiff]({{< ref "/develop/permadiff.md" >}}) for more information and best practices.
+[Fix diffs]({{< ref "/develop/diffs" >}}) for more information and best practices.
 
 The function specified can be a
 [provider-specific function](https://github.com/hashicorp/terraform-provider-google-beta/blob/main/google-beta/tpgresource/common_diff_suppress.go)

docs/content/develop/test/run-tests.md

@@ -113,6 +113,13 @@ aliases:
 
 {{< /tabs >}}
 
+### Common errors
+
+- `After applying this test step, the plan was not empty.`
+  - See [Fix diffs]({{< ref "/develop/diffs" >}}).
+- `Blocks of type "FIELD_NAME" are not expected here`
+  - The field does not exist; this is either because it has not been implemented or because the test is running for the `google` provider and the field is only implemented in the `google-beta` provider. See [Add resource tests]({{< ref "/develop/test/test" >}}) for information on using version guards to exclude beta-only fields from GA tests, or [Promote from beta to GA]({{< ref "/develop/promote-to-ga" >}}) for information on how to promote fields that were accidentally made beta-only.
+
 ## Optional: Test with different `terraform` versions
 
 Tests will use whatever version of the `terraform` binary is found on your `PATH`. If you are testing a change that you know only impacts certain `terraform` versions, follow these steps: