diff --git a/content/tour/stages.md b/content/tour/stages.md
index c59ce178e..2aa6dc52a 100644
--- a/content/tour/stages.md
+++ b/content/tour/stages.md
@@ -60,6 +60,10 @@ stages:
           - echo "Goodbye, World"
 ```
 
+{{% alert title="Note:" color="info" %}}
+Be aware that `needs:` references stages by their name, which can be overridden by the `name` tag in the stage definition.
+{{% /alert %}}
+
 ```sh
 $ vela exec pipeline
 ...
diff --git a/content/usage/stage_orchestration.md b/content/usage/stage_orchestration.md
index 6be40e0a3..e308c088a 100644
--- a/content/usage/stage_orchestration.md
+++ b/content/usage/stage_orchestration.md
@@ -130,6 +130,10 @@ stages:
           - echo $VELA_REPO_FULL_NAME
 ```
 
+{{% alert title="Note:" color="info" %}}
+Be aware that `needs:` references stages by their name, which can be overridden by the `name` tag in the stage definition.
+{{% /alert %}}
+
 Consider a Vela build triggered by a `push` to `main`. We know that `run-first` will indeed run first, followed by `runtime-ruleset-stage` since it cannot be pruned due to its runtime rule. However, if we recall from our first example, when the _entirety_ of a stage's step collection is pruned at compile-time, the stage disappears completely:
 
 ```yaml