diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
index cfa85b379a..359df8f75f 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
@@ -840,6 +840,18 @@
is a global variable and is always automatically
available.
+
+
+ Variable expressions (e.g. ${X}) are no
+ longer expanded within Python functions.
+ This behavior is intentional in order to allow you to freely
+ set variable values to expandable expressions without having
+ them expanded prematurely.
+ If you do wish to expand a variable within a Python function,
+ use d.getVar("X", True).
+ Or, for more complicated expressions, use
+ d.expand().
+