diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 95e07f85a..839a89d4b 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -2130,6 +2130,18 @@ section in the Yocto Project Development Tasks Manual.

 Previously, this class was called the ``task`` class.

+.. note::
+
+   If you're defining a packagegroup and need to set::
+
+      PACKAGE_ARCH = ${MACHINE_ARCH}
+
+   for the packagegroup, you need to do that *before* the
+   ``inherit packagegroup`` line in the recipe file.
+   Setting it afterward can break BitBake parsing, result in
+   an "allarch" architecture mismatch error, or allow
+   architecture-independent defaults to override your intent.
+
 .. _ref-classes-patch:

 ``patch``