diff --git a/documentation/dev-manual/building.rst b/documentation/dev-manual/building.rst
index 9983c7939..d4f1544bb 100644
--- a/documentation/dev-manual/building.rst
+++ b/documentation/dev-manual/building.rst
@@ -615,6 +615,18 @@ your tunings to best consider build times and package feed maintenance.

       PACKAGE_ARCH = "${TUNE_PKGARCH}"

+   .. note::
+
+      If you're defining a packagegroup and you want 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.
+
 -  *Choose a Generic Tuning File if Possible:* Some tunes are more
    generic and can run on multiple targets (e.g. an ``armv5`` set of
    packages could run on ``armv6`` and ``armv7`` processors in most