diff --git a/src/content/docs/workers/wrangler/system-environment-variables.mdx b/src/content/docs/workers/wrangler/system-environment-variables.mdx
index 46f72a49a8166e1..17e5b41100bd928 100644
--- a/src/content/docs/workers/wrangler/system-environment-variables.mdx
+++ b/src/content/docs/workers/wrangler/system-environment-variables.mdx
@@ -16,6 +16,11 @@ System environment variables are local environment variables that can change Wra
 
 3. Set the values in your shell environment. For example, if you are using Z shell, adding `export CLOUDFLARE_API_TOKEN=...` to your `~/.zshrc` file will set this token as part of your shell configuration.
 
+:::note
+
+You can set system environment variables per environment by creating additional files with the naming convention `.env.<environment-name>`. When you set the environment using `wrangler <command> --env <environment-name>`, such an environment specific file will be loaded instead of the `.env` file - they are not merged.
+:::
+
 ## Supported environment variables
 
 Wrangler supports the following environment variables:
diff --git a/src/content/partials/workers/secrets-in-dev.mdx b/src/content/partials/workers/secrets-in-dev.mdx
index 9f95cf6c5cee8ad..64e701da9829eb1 100644
--- a/src/content/partials/workers/secrets-in-dev.mdx
+++ b/src/content/partials/workers/secrets-in-dev.mdx
@@ -12,4 +12,6 @@ SECRET_KEY="value"
 API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
 ```
 
-You can set secrets per environment by creating additional files with the naming convention `.dev.vars.<environment-name>`. Like other environment variables, secrets are [non-inheritable](/workers/wrangler/configuration/#non-inheritable-keys) and must be defined per environment.
+You can set secrets per environment by creating additional files with the naming convention `.dev.vars.<environment-name>`. When you set the environment using `wrangler <command> --env <environment-name>`, such an environment specific file will be loaded instead of the `.dev.vars` file - they are not merged.
+
+Like other environment variables, secrets are [non-inheritable](/workers/wrangler/configuration/#non-inheritable-keys) and must be defined per environment.