diff --git a/docs/maintainers/handbook.md b/docs/maintainers/handbook.md
index 6c668da..13398c2 100644
--- a/docs/maintainers/handbook.md
+++ b/docs/maintainers/handbook.md
@@ -88,13 +88,26 @@ export NGINX_CONFIG_VERSION=v1
 
 ## Manage environment variables
 
-When you define an environment variable in a `.env.sample` for a recipe, such as:
+!!! warning
+
+    Please read this section carefully to avoid deployment footguns for the
+    operators who deploy your recipe configuration. It's important to
+    understand how to add new env vars into the recipe configuration in a
+    non-breaking manner. Thanks for reading!
+
+When you define an environment variable in an `.env.sample` for a recipe, such as:
 
 ```bash
 FOO=123
 ```
 
-And you pass this via the `environment` stanza of a service config in the recipe like so:
+This defines an env var which then needs to be added by an operator to their app env file. If you would like to add an env var which is optional, you can do:
+
+```bash
+#FOO=123
+```
+
+In order to expose this env var to recipe configuration, you pass this via the `environment` stanza of a service config in the recipe like so:
 
 ```yaml
 service: