diff --git a/doc/source/execution.rst b/doc/source/execution.rst
index 7cf0ec379..aa75f43a3 100644
--- a/doc/source/execution.rst
+++ b/doc/source/execution.rst
@@ -25,7 +25,7 @@ job_builder section
 **include_path**
   (Optional) Can be set to a ':' delimited list of paths, which jenkins
   job builder will search for any files specified by the custom application
-  yaml tags 'include', 'include-raw' and 'include-raw-escaped'.
+  yaml tags 'include', 'include-raw' and 'include-raw-escape'.
 
 **recursive**
   (Optional) If set to True, jenkins job builder will search for job
diff --git a/jenkins_jobs/local_yaml.py b/jenkins_jobs/local_yaml.py
index 473b592de..a989eaba5 100644
--- a/jenkins_jobs/local_yaml.py
+++ b/jenkins_jobs/local_yaml.py
@@ -65,6 +65,15 @@ before being read in as string data. This allows job-templates to use this tag
 to include scripts from files without needing to escape braces in the original
 file.
 
+.. warning::
+
+    When used as a macro ``!include-raw-escape:`` should only be used if
+    parameters are passed into the escaped file and you would like to escape
+    those parameters. If the file does not have any jjb parameters passed into
+    it then ``!include-raw:`` should be used instead otherwise you will run
+    into an interesting issue where ``include-raw-escape:`` actually adds
+    additional curly braces around existing curly braces. For example
+    ${PROJECT} becomes ${{PROJECT}} which may break bash scripts.
 
 Examples: