docs: Improve documentation on lifecycle hooks (argoproj#10911)

Signed-off-by: Alan Clucas <alan@clucas.org>

docs/lifecyclehook.md

@@ -4,28 +4,28 @@
 
 ## Introduction
 
-A [`LifecycleHook`](https://argoproj.github.io/argo-workflows/fields/#lifecyclehook) triggers an action based on a conditional expression. It is configured either at the workflow-level or template-level, for instance as a function of the `workflow.status` or `steps.status`, respectively. A `LifecycleHook` executes during execution time and executes once.
+A [`LifecycleHook`](https://argoproj.github.io/argo-workflows/fields/#lifecyclehook) triggers an action based on a conditional expression or on completion of a step or template. It is configured either at the workflow-level or template-level, for instance as a function of the `workflow.status` or `steps.status`, respectively. A `LifecycleHook` executes during execution time and executes once. It will execute in parallel to its step or template once the expression is satisfied.
 
-In other words, a `LifecycleHook` functions like an [exit handler](https://github.com/argoproj/argo-workflows/blob/master/examples/exit-handlers.yaml) with a conditional expression.
+In other words, a `LifecycleHook` functions like an [exit handler](https://github.com/argoproj/argo-workflows/blob/master/examples/exit-handlers.yaml) with a conditional expression. You must not name a `LifecycleHook` `exit` or it becomes an exit handler, otherwise the hook name has no relevance.
 
-**Workflow-level `LifecycleHook`**: Executes the workflow when a configured expression is met.
+**Workflow-level `LifecycleHook`**: Executes the template when a configured expression is met during the workflow.
 
-- [Workflow-level Lifecycle-Hook example](https://github.com/argoproj/argo-workflows/blob/45730a9cdeb588d0e52b1ac87b6e0ca391a95a81/examples/life-cycle-hooks-wf-level.yaml)
+- [Workflow-level Lifecycle-Hook example](https://github.com/argoproj/argo-workflows/blob/master/examples/life-cycle-hooks-wf-level.yaml)
 
-**Template-level Lifecycle-Hook**: Executes the template when a configured expression is met.
+**Template-level `Lifecycle-Hook`**: Executes the template when a configured expression is met during the step in which it is defined.
 
-- [Template-level Lifecycle-Hook example](https://github.com/argoproj/argo-workflows/blob/45730a9cdeb588d0e52b1ac87b6e0ca391a95a81/examples/life-cycle-hooks-tmpl-level.yaml)
+- [Template-level Lifecycle-Hook example](https://github.com/argoproj/argo-workflows/blob/master/examples/life-cycle-hooks-tmpl-level.yaml)
 
 ## Supported conditions
 
-- [Exit handler variables](https://github.com/argoproj/argo-workflows/blob/ebd3677c7a9c973b22fa81ef3b409404a38ec331/docs/variables.md#exit-handler): `workflow.status` and `workflow.failures`
+- [Exit handler variables](https://github.com/argoproj/argo-workflows/blob/master/docs/variables.md#exit-handler): `workflow.status` and `workflow.failures`
 - [`template`](https://argoproj.github.io/argo-workflows/fields/#template)
 - [`templateRef`](https://argoproj.github.io/argo-workflows/fields/#templateref)
 - [`arguments`](https://github.com/argoproj/argo-workflows/blob/master/examples/conditionals.yaml)
 
 ## Unsupported conditions
 
-- [`outputs`](https://argoproj.github.io/argo-workflows/fields/#outputs) are not usable since `LifecycleHook` executes during execution time and `outputs` are not produced until the step is completed.
+- [`outputs`](https://argoproj.github.io/argo-workflows/fields/#outputs) are not usable since `LifecycleHook` executes during execution time and `outputs` are not produced until the step is completed. You can use outputs from previous steps, just not the one you're hooking into. If you'd like to use outputs create an exit handler instead - all the status variable are available there so you can still conditionally decide what to do.
 
 ## Notification use case
 

examples/life-cycle-hooks-tmpl-level.yaml

@@ -9,7 +9,7 @@
           steps:
             - - name: step-1
                 hooks:
-                  exit:
+                  running: # Name of hook does not matter
                     # Expr will not support `-` on variable name. Variable should wrap with `[]`
                     expression: steps["step-1"].status == "Running"
                     template: http
@@ -19,20 +19,20 @@
                 template: echo
             - - name: step2
                 hooks:
-                  exit:
+                  running:
                     expression: steps.step2.status == "Running"
                     template: http
                   success:
                     expression: steps.step2.status == "Succeeded"
                     template: http
                 template: echo
-        
+
         - name: echo
           container:
             image: alpine:3.6
             command: [sh, -c]
             args: ["echo \"it was heads\""]
-        
+
         - name: http
           http:
             # url: http://dummy.restapiexample.com/api/v1/employees

examples/life-cycle-hooks-wf-level.yaml

@@ -5,7 +5,7 @@ metadata:
 spec:
   entrypoint: main
   hooks:
-    exit:
+    exit: # Exit handler
       template: http
     running:
       expression: workflow.status == "Running"