diff --git a/documentation/src/main/asciidoc/introduction/Advanced.adoc b/documentation/src/main/asciidoc/introduction/Advanced.adoc
index ae1a3f7f9661..9dae0bab7412 100644
--- a/documentation/src/main/asciidoc/introduction/Advanced.adoc
+++ b/documentation/src/main/asciidoc/introduction/Advanced.adoc
@@ -994,9 +994,18 @@ plugins {
     id "org.hibernate.orm" version "{fullVersion}"
 }
 
-hibernate { enhancement }
+hibernate {
+  enhancement {}
+}
 ----
 
+[CAUTION]
+====
+Some online documentation (including previous versions of the present one) suggest to use `hibernate { enhancement }`, which will _not_ work as it is interpreted by Gradle as a (pointless) getter call instead of actual configuration.
+That form will result in bytecode enhancement NOT happening (unfortunately silently).
+To enable bytecode enhancement, make sure to always use the block form (with `{}`).
+====
+
 // [discrete]
 // ==== Attribute-level lazy fetching
 
diff --git a/migration-guide.adoc b/migration-guide.adoc
index b0f565e8c168..eba0b2d69465 100644
--- a/migration-guide.adoc
+++ b/migration-guide.adoc
@@ -92,6 +92,21 @@ Applications should instead use proper object-oriented encapsulation, exposing m
 
 Additionally, attempting to re-enhance a class with different options is no longer allowed and will result in a `FeatureMismatchException`.
 
+The Gradle plugin configuration has changed slightly. When using the default setup:
+
+```
+hibernate { enhancement }
+```
+
+it should be updated to:
+
+```
+hibernate {
+    enhancement {}
+}
+```
+
+in order to properly enable Bytecode Enhancement.
 
 [[session-getLobHelper]]
 === Session#getLobHelper