diff --git a/core/core-modules.el b/core/core-modules.el
index 4ede84888..2bf2d0737 100644
--- a/core/core-modules.el
+++ b/core/core-modules.el
@@ -459,7 +459,8 @@ two extra properties:
 (defmacro use-package-hook! (package when &rest body)
   "Reconfigures a package's `use-package!' block.
 
-Only use this macro in a module's init.el file.
+This macro must be used *before* PACKAGE's `use-package!' block. Often, this
+means using it from your DOOMDIR/init.el.
 
 Under the hood, this uses use-package's `use-package-inject-hooks'.
 
@@ -467,9 +468,13 @@ PACKAGE is a symbol; the package's name.
 WHEN should be one of the following:
   :pre-init :post-init :pre-config :post-config
 
-WARNING: If :pre-init or :pre-config hooks return nil, the original
-`use-package!''s :init/:config block (respectively) is overwritten, so remember
-to have them return non-nil (or exploit that to overwrite Doom's config)."
+WARNINGS:
+- The use of this macro is more often than not a code smell. Use it as last
+  resort. There is almost always a better alternative.
+- If you are using this solely for :post-config, stop! `after!' is much better.
+- If :pre-init or :pre-config hooks return nil, the original `use-package!''s
+  :init/:config block (respectively) is overwritten, so remember to have them
+  return non-nil (or exploit that to overwrite Doom's config)."
   (declare (indent defun))
   (unless (memq when '(:pre-init :post-init :pre-config :post-config))
     (error "'%s' isn't a valid hook for use-package-hook!" when))