diff --git a/docs/static/env-vars.asciidoc b/docs/static/env-vars.asciidoc
index 2c39eddee58..1b090e1c927 100644
--- a/docs/static/env-vars.asciidoc
+++ b/docs/static/env-vars.asciidoc
@@ -12,7 +12,7 @@ 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 in `config.string` comments are not allowed. Remove the `$` sign to avoid pipeline config failures.
+* Environment variables references in `config.string` comments are not allowed. Remove the `$` sign to avoid pipeline config failures.
 
 ==== Examples
 
diff --git a/docs/static/pipeline-configuration.asciidoc b/docs/static/pipeline-configuration.asciidoc
index 1c075c48717..843c3fb5c66 100644
--- a/docs/static/pipeline-configuration.asciidoc
+++ b/docs/static/pipeline-configuration.asciidoc
@@ -310,7 +310,7 @@ input { # comments can appear at the end of a line, too
   # ...
 }
 ----------------------------------
-NOTE: Due to a substitution logic, commenting environment `${var}` in `config.string` is not allowed. Remove the `$` sign to avoid pipeline config failures.
+NOTE: Comments containing environment `${var}` references in `config.string` are not allowed. Remove the `$` sign to avoid pipeline loading failures.
 
 include::event-data.asciidoc[]
 include::env-vars.asciidoc[]