diff --git a/docs/static/env-vars.asciidoc b/docs/static/env-vars.asciidoc
index 1b090e1c927..5991898f1a8 100644
--- a/docs/static/env-vars.asciidoc
+++ b/docs/static/env-vars.asciidoc
@@ -12,7 +12,8 @@ environment variable is undefined.
 * You can add environment variable references in any plugin option type: string, number, boolean, array, or hash.
 * Environment variables for list-type URI parameters can support lists of space-delimited values. Currently, other non-URI based options do not support lists of values. See <<plugin-concepts>>
 * Environment variables are immutable. If you update the environment variable, you'll have to restart Logstash to pick up the updated value.
-* Environment variables references in `config.string` comments are not allowed. Remove the `$` sign to avoid pipeline config failures.
+* References to environment variables in `config.string` comments will still be evaluated during configuration parsing and are therefore discouraged.
+Remove the `$` sign to avoid pipeline loading failures.
 
 ==== Examples
 
diff --git a/docs/static/pipeline-configuration.asciidoc b/docs/static/pipeline-configuration.asciidoc
index 843c3fb5c66..eefe62bca8f 100644
--- a/docs/static/pipeline-configuration.asciidoc
+++ b/docs/static/pipeline-configuration.asciidoc
@@ -310,7 +310,8 @@ input { # comments can appear at the end of a line, too
   # ...
 }
 ----------------------------------
-NOTE: Comments containing environment `${var}` references in `config.string` are not allowed. Remove the `$` sign to avoid pipeline loading failures.
+NOTE: Comments containing environment variable `${var}` references in `config.string` will still be evaluated.
+Remove the `$` sign to avoid pipeline loading failures.
 
 include::event-data.asciidoc[]
 include::env-vars.asciidoc[]