diff --git a/docs/docs/api_reference.md b/docs/docs/api_reference.md
index 7a5e02c9..a62266b2 100644
--- a/docs/docs/api_reference.md
+++ b/docs/docs/api_reference.md
@@ -214,6 +214,19 @@ vars:
 
 :::
 
+:::info
+
+In a variables map, variables defined later may reference variables defined
+earlier (declaration order is respected):
+
+```yaml
+vars:
+  FIRST_VAR: "hello"
+  SECOND_VAR: "{{.FIRST_VAR}} world"
+```
+
+:::
+
 ### Task
 
 | Attribute       | Type                               | Default                                               | Description                                                                                                                                                                                                                                                                                              |