Merge pull request #30487 from hashicorp/update-depends-on-docs

Update depends_on documentation

website/docs/language/meta-arguments/depends_on.mdx

@@ -7,24 +7,30 @@ description: >-
 
 # The `depends_on` Meta-Argument
 
--> **Version note:** Module support for `depends_on` was added in Terraform 0.13, and
-previous versions can only use it with resources.
+Use the `depends_on` meta-argument to handle hidden resource or module dependencies that Terraform cannot automatically infer. You only need to explicitly specify a dependency when a resource or module relies on another resource's behavior but does not access any of that resource's data in its arguments.
 
-Use the `depends_on` meta-argument to handle hidden resource or module dependencies that
-Terraform can't automatically infer.
+-> **Note:** Module support for `depends_on` was added in Terraform version 0.13, and prior versions can only use it with resources.
 
-Explicitly specifying a dependency is only necessary when a resource or module relies on
-some other resource's behavior but _doesn't_ access any of that resource's data
-in its arguments.
 
-This argument is available in `module` blocks and in all `resource` blocks,
-regardless of resource type. For example:
+## Processing and Planning Consequences
+
+The `depends_on` meta-argument instructs Terraform to complete all actions on the the dependency object (including Read actions) before performing actions on the object declaring the dependency. When one the dependency object is an entire module, `depends_on` affects the order in which Terraform processes all of the resources and data sources associated with that module. Refer to [Resource Dependencies](/language/resources/behavior#resource-dependencies) and [Data Resource Dependencies](/language/data-sources#data-resource-dependencies) for more details.
+
+You should use `depends_on` as a last resort because it can cause Terraform to create more conservative plans that replace more resources than necessary. For example, Terraform may treat more values as unknown “(known after apply)” because it is uncertain what changes will occur on the upstream object. This is especially likely when you use `depends_on` for modules.
+
+Instead of `depends_on`, we recommend using [expression references](/language/expressions/references) to imply dependencies when possible. Expression references let Terraform understand which value the reference derives from and avoid planning changes if that particular value hasn’t changed, even if other parts of the upstream object have planned changes.
+
+## Usage
+
+You can use the `depends_on` meta-argument in `module` blocks and in all `resource` blocks, regardless of resource type. It requires a list of references to other resources or child modules in the same calling module. This list cannot include arbitrary expressions because the `depends_on` value must be known before Terraform knows resource relationships and thus before it can safely evaluate expressions.
+
+We recommend always including a comment that explains why using `depends_on` is necessary. The following example uses `depends_on` to handle a "hidden" dependency on the `aws_iam_instance_profile.example`.
 
 ```hcl
 resource "aws_iam_role" "example" {
   name = "example"
 
-  # assume_role_policy is omitted for brevity in this example. See the
+  # assume_role_policy is omitted for brevity in this example. Refer to the
   # documentation for aws_iam_role for a complete example.
   assume_role_policy = "..."
 }
@@ -64,14 +70,4 @@ resource "aws_instance" "example" {
     aws_iam_role_policy.example,
   ]
 }
-```
-
-The `depends_on` meta-argument, if present, must be a list of references
-to other resources or child modules in the same calling module.
-Arbitrary expressions are not allowed in the `depends_on` argument value,
-because its value must be known before Terraform knows resource relationships
-and thus before it can safely evaluate expressions.
-
-The `depends_on` argument should be used only as a last resort. When using it,
-always include a comment explaining why it is being used, to help future
-maintainers understand the purpose of the additional dependency.
+```