diff --git a/docs/docs/api_reference.md b/docs/docs/api_reference.md
index 06dd4e2181..6595de0e49 100644
--- a/docs/docs/api_reference.md
+++ b/docs/docs/api_reference.md
@@ -128,7 +128,7 @@ There are some special variables that is available on the templating system:
 | `CHECKSUM`         | The checksum of the files listed in `sources`. Only available within the `status` prop and if method is set to `checksum`.                               |
 | `TIMESTAMP`        | The date object of the greatest timestamp of the files listed in `sources`. Only available within the `status` prop and if method is set to `timestamp`. |
 | `TASK_VERSION`     | The current version of task.                                                                                                                             |
-| `ITEM`             | The value of the current iteration when using the `for` property.                                                                                        |
+| `ITEM`             | The value of the current iteration when using the `for` property. Can be changed to a different variable name using `as:`.                                                                                        |
 
 ## ENV
 
diff --git a/docs/docs/usage.md b/docs/docs/usage.md
index 774be62689..19ebc99207 100644
--- a/docs/docs/usage.md
+++ b/docs/docs/usage.md
@@ -1043,7 +1043,9 @@ match that glob.
 
 Source paths will always be returned as paths relative to the task directory. If
 you need to convert this to an absolute path, you can use the built-in
-`joinPath` function:
+`joinPath` function.
+There are some [special variables](/api/#special-variables) that you may find
+useful for this.
 
 ```yaml
 version: '3'
@@ -1058,7 +1060,7 @@ tasks:
       - bar.txt
     cmds:
       - for: sources
-        cmd: cat {{ joinPath .MY_DIR .ITEM }}
+        cmd: cat {{joinPath .MY_DIR .ITEM}}
 ```
 
 ### Looping over variables
@@ -1073,11 +1075,10 @@ version: '3'
 tasks:
   default:
     vars:
-      my_var: foo.txt bar.txt
+      MY_VAR: foo.txt bar.txt
     cmds:
-      - for:
-          var: my_var
-        cmd: cat {{ .ITEM }}
+      - for: { var: MY_VAR }
+        cmd: cat {{.ITEM}}
 ```
 
 If you need to split on a different character, you can do this by specifying the
@@ -1089,12 +1090,10 @@ version: '3'
 tasks:
   default:
     vars:
-      my_var: foo.txt,bar.txt
+      MY_VAR: foo.txt,bar.txt
     cmds:
-      - for:
-          var: my_var
-          split: ','
-        cmd: cat {{ .ITEM }}
+      - for: { var: MY_VAR, split: ',' }
+        cmd: cat {{.ITEM}}
 ```
 
 All of this also works with dynamic variables!
@@ -1105,12 +1104,11 @@ version: '3'
 tasks:
   default:
     vars:
-      my_var:
+      MY_VAR:
         sh: find -type f -name '*.txt'
     cmds:
-      - for:
-          var: my_var
-        cmd: cat {{ .ITEM }}
+      - for: { var: MY_VAR }
+        cmd: cat {{.ITEM}}
 ```
 
 ### Renaming variables
@@ -1124,12 +1122,10 @@ version: '3'
 tasks:
   default:
     vars:
-      my_var: foo.txt bar.txt
+      MY_VAR: foo.txt bar.txt
     cmds:
-      - for:
-          var: my_var
-          as: FILE
-        cmd: cat {{ .FILE }}
+      - for: { var: MY_VAR, as: FILE }
+        cmd: cat {{.FILE}}
 ```
 
 ### Looping over tasks
@@ -1147,11 +1143,11 @@ tasks:
       - for: [foo, bar]
         task: my-task
         vars:
-          FILE: '{{ .ITEM }}'
+          FILE: '{{.ITEM}}'
 
   my-task:
     cmds:
-      - echo '{{ .FILE }}'
+      - echo '{{.FILE}}'
 ```
 
 Or if you want to run different tasks depending on the value of the loop:
@@ -1163,7 +1159,7 @@ tasks:
   default:
     cmds:
       - for: [foo, bar]
-        task: task-{{ .ITEM }}
+        task: task-{{.ITEM}}
 
   task-foo:
     cmds: