From 669d4a4e986b359dde3cd07e5616be8f713fe23d Mon Sep 17 00:00:00 2001
From: Anton Gilgur <4970083+agilgur5@users.noreply.github.com>
Date: Mon, 17 Jun 2024 01:10:08 -0400
Subject: [PATCH] docs: full copy-edit of enhanced `depends` page (#13110)

Signed-off-by: Anton Gilgur <agilgur5@gmail.com>
---
 docs/enhanced-depends-logic.md | 51 +++++++++++++---------------------
 1 file changed, 20 insertions(+), 31 deletions(-)

diff --git a/docs/enhanced-depends-logic.md b/docs/enhanced-depends-logic.md
index 64328d0005c3..f5eaa11df6b8 100644
--- a/docs/enhanced-depends-logic.md
+++ b/docs/enhanced-depends-logic.md
@@ -2,35 +2,26 @@
 
 > v2.9 and after
 
-## Introduction
-
-Previous to version 2.8, the only way to specify dependencies in DAG templates was to use the `dependencies` field and
-specify a list of other tasks the current task depends on. This syntax was limiting because it does not allow the user to
-specify which _result_ of the task to depend on. For example, a task may only be relevant to run if the dependent task
-succeeded (or failed, etc.).
+Enhanced `depends` improves on [the `dependencies` field](walk-through/dag.md) by specifying which _result_ of a task to depend on.
+For example, to only run a task if its dependent task succeeded.
 
 ## Depends
 
-To remedy this, there exists a new field called `depends`, which allows users to specify dependent tasks, their statuses,
-as well as any complex boolean logic. The field is a `string` field and the syntax is expression-like with operands having
-form `<task-name>.<task-result>`. Examples include `task-1.Succeeded`, `task-2.Failed`, `task-3.Daemoned`. The full list of
-available task results is as follows:
-
-|  Task Result | Description    | Meaning |
-|:------------:|----------------|---------|
-| `.Succeeded` | Task Succeeded | Task finished with no error |
-| `.Failed` | Task Failed | Task exited with a non-0 exit code |
-| `.Errored` | Task Errored | Task had an error other than a non-0 exit code |
-| `.Skipped` | Task Skipped | Task was skipped |
-| `.Omitted` | Task Omitted | Task was omitted |
-| `.Daemoned` | Task is Daemoned and is not Pending | |
+You can use the `depends` field to specify dependent tasks, their results, and boolean logic between them.
 
-A tasks is considered `Skipped` if its `when` condition evaluates to false. On the other hand, if a task doesn't run
-because its `depends` evaluated to false it is `Omitted`.
+You use operands of the form `<task-name>.<task-result>`, such as `task-1.Succeeded`, `task-2.Failed`, `task-3.Daemoned`.
+Available task results are:
 
-For convenience, an omitted task result is equivalent to `(task.Succeeded || task.Skipped || task.Daemoned)`.
+|  Task Result | Description |
+|:------------:|-------------|
+| `.Succeeded` | Task finished with no error |
+| `.Failed`    | Task exited with a non-0 exit code |
+| `.Errored`   | Task had an error other than a non-0 exit code |
+| `.Skipped`   | Task's [`when`](walk-through/conditionals.md) condition evaluated to `false` |
+| `.Omitted`   | Task's `depends` condition evaluated to `false` |
+| `.Daemoned`  | Task is [daemoned](walk-through/daemon-containers.md) and is not `Pending` |
 
-For example:
+For compatibility with `dependencies`, an unspecified result is equivalent to `(task.Succeeded || task.Skipped || task.Daemoned)`. For example:
 
 ```yaml
 depends: "task || task-2.Failed"
@@ -42,20 +33,19 @@ is equivalent to:
 depends: (task.Succeeded || task.Skipped || task.Daemoned) || task-2.Failed
 ```
 
-Full boolean logic is also available. Operators include:
+You can use boolean logic with the operators:
 
 * `&&`
 * `||`
 * `!`
 
- Example:
+Example:
 
 ```yaml
 depends: "(task-2.Succeeded || task-2.Skipped) && !task-3.Failed"
 ```
 
-In the case that you're depending on a task that uses `withItems`, you can depend on
-whether any of the item tasks are successful or all have failed using `.AnySucceeded` and `.AllFailed`, for example:
+If you depend on a task that uses `withItems`, you can use `.AnySucceeded` and `.AllFailed`. For example:
 
 ```yaml
 depends: "task-1.AnySucceeded || task-2.AllFailed"
@@ -63,9 +53,9 @@ depends: "task-1.AnySucceeded || task-2.AllFailed"
 
 ## Compatibility with `dependencies` and `dag.task.continueOn`
 
-This feature is fully compatible with `dependencies` and conversion is easy.
+You cannot use both `dependencies` and `depends` in the same task group.
 
-To convert simply join your `dependencies` with `&&`:
+To convert from `dependencies` to `depends`, join your array into a string with `&&`. For example:
 
 ```yaml
 dependencies: ["A", "B", "C"]
@@ -77,5 +67,4 @@ is equivalent to:
 depends: "A && B && C"
 ```
 
-Because of the added control found in `depends`, the `dag.task.continueOn` is not available when using it. Furthermore,
-it is not possible to use both `dependencies` and `depends` in the same task group.
+`dag.task.continueOn` is not available when using `depends`; instead you can specify `.Failed`.