From de07bcf127cfd48df5b38c0d7c1fc701c7284aa6 Mon Sep 17 00:00:00 2001
From: Alan Clucas <alan@clucas.org>
Date: Fri, 10 Mar 2023 09:47:28 +0000
Subject: [PATCH] docs: Improve documentation on loops

Signed-off-by: Alan Clucas <alan@clucas.org>
---
 docs/walk-through/loops.md | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/docs/walk-through/loops.md b/docs/walk-through/loops.md
index 6c04a702aead..c898316d887c 100644
--- a/docs/walk-through/loops.md
+++ b/docs/walk-through/loops.md
@@ -1,6 +1,14 @@
 # Loops
 
-When writing workflows, it is often very useful to be able to iterate over a set of inputs as shown in this example:
+When writing workflows, it is often very useful to be able to iterate over a set of inputs.
+
+There are two basic ways of running a template multiple times.
+- `withItems` takes a list of things to work on. Either
+  - plain, single values, which are then usable in your template as '{{item}}'
+  - a json object where each element in the object can be addressed by it's key as '{{item.key}}'
+- `withParams` takes a json array of items, and iterates over it - again the items can be objects like with `withItems`. This is very powerful, as you can generate the json in another step in your workflow, so creating a dynamic workflow.
+
+This example is the simplest. We are taking a basic list of items and iterating over it with `withItems`. It is limited to one varying field for each of the workflow templates instatiated.
 
 ```yaml
 apiVersion: argoproj.io/v1alpha1
@@ -32,7 +40,7 @@ spec:
       args: ["{{inputs.parameters.message}}"]
 ```
 
-We can also iterate over sets of items:
+If we'd like more than one piece of information in each workflow, you can instead pass a json object to `withItems` and then address the elements by key, as shown in this example.
 
 ```yaml
 apiVersion: argoproj.io/v1alpha1
@@ -42,7 +50,9 @@ metadata:
 spec:
   entrypoint: loop-map-example
   templates:
-  - name: loop-map-example
+  - name: loop-map-example parameter specifies the list to iterate over
+
+
     steps:
     - - name: test-linux
         template: cat-os-release
@@ -69,7 +79,7 @@ spec:
       args: [/etc/os-release]
 ```
 
-We can pass lists of items as parameters:
+This example does exactly the same job as the previous example, but using `withParam` to pass the information as a JSON array argument, instead of directly hardcoded into the template.
 
 ```yaml
 apiVersion: argoproj.io/v1alpha1
@@ -117,7 +127,7 @@ spec:
       args: [/etc/os-release]
 ```
 
-We can even dynamically generate the list of items to iterate over!
+Finally, the most powerful form of this is to generate that JSON array of objects dynamically in one step, and then pass it to the next step so that the number and values used in the second step are only calculated at runtime.
 
 ```yaml
 apiVersion: argoproj.io/v1alpha1