diff --git a/core/compiler/compiler-docs.factor b/core/compiler/compiler-docs.factor
index 7196a4b4fb..3520104e1f 100755
--- a/core/compiler/compiler-docs.factor
+++ b/core/compiler/compiler-docs.factor
@@ -8,7 +8,8 @@ $nl
 "The main entry point to the optimizing compiler:"
 { $subsection optimized-recompile-hook }
 "Removing a word's optimized definition:"
-{ $subsection decompile } ;
+{ $subsection decompile }
+"These words are not usually used directly. Instead, use " { $link "compilation-units" } "." ;
 
 ARTICLE: "compiler" "Optimizing compiler"
 "Factor is a fully compiled language implementation with two distinct compilers:"
diff --git a/core/compiler/units/units-docs.factor b/core/compiler/units/units-docs.factor
index 74dac17be8..09baf91018 100755
--- a/core/compiler/units/units-docs.factor
+++ b/core/compiler/units/units-docs.factor
@@ -9,7 +9,9 @@ $nl
 $nl
 "The parser groups all definitions in a source file into one compilation unit, and parsing words do not need to concern themselves with compilation units. However, if definitions are being created at run time, a compilation unit must be created explicitly:"
 { $subsection with-compilation-unit }
-"Words called to associate a definition with a source file location:"
+"Compiling a set of words:"
+{ $subsection compile }
+"Words called to associate a definition with a compilation unit and a source file location:"
 { $subsection remember-definition }
 { $subsection remember-class }
 "Forward reference checking (see " { $link "definition-checking" } "):"
diff --git a/core/syntax/syntax-docs.factor b/core/syntax/syntax-docs.factor
index 26562a2178..c0ceb4119a 100755
--- a/core/syntax/syntax-docs.factor
+++ b/core/syntax/syntax-docs.factor
@@ -227,6 +227,9 @@ HELP: foldable
     }
     "The last restriction ensures that words such as " { $link clone } " do not satisfy the foldable word contract. Indeed, " { $link clone } " will output a mutable object if its input is mutable, and so it is undesirable to evaluate it at compile-time, since doing so would give incorrect semantics for code that clones mutable objects and proceeds to mutate them."
 }
+{ $notes
+    "Folding optimizations are not applied if the call site of a word is in the same source file as the word. This is a side-effect of the compilation unit system; see " { $link "compilation-units" } "."
+}
 { $examples "Most operations on numbers are foldable. For example, " { $snippet "2 2 +" } " compiles to a literal 4, since " { $link + } " is declared foldable." } ;
 
 HELP: flushable