diff --git a/modules/misc/news.nix b/modules/misc/news.nix
index a94fa6c0e..9fa842cc9 100644
--- a/modules/misc/news.nix
+++ b/modules/misc/news.nix
@@ -2084,6 +2084,25 @@ in
           A new module is available: 'programs.mangohud'.
         '';
       }
+
+      {
+        time = "2021-06-16T01:26:16+00:00";
+        message = ''
+          The xmonad module now compiles the configuration before
+          linking the binary to the place xmonad expects to find
+          the compiled configuration (the binary).
+
+          This breaks recompilation of xmonad (i.e. the 'q' binding or
+          'xmonad --recompile').
+
+          If this behavior is undesirable, do not use the
+          'xsession.windowManager.xmonad.config' option. Instead, set the
+          contents of the configuration file with
+          'home.file.".xmonad/config.hs".text = "content of the file"'
+          or 'home.file.".xmonad/config.hs".source = ./path-to-config'.
+        '';
+      }
+
     ];
   };
 }
diff --git a/modules/services/window-managers/xmonad.nix b/modules/services/window-managers/xmonad.nix
index 07ed2846f..6d05d68ed 100644
--- a/modules/services/window-managers/xmonad.nix
+++ b/modules/services/window-managers/xmonad.nix
@@ -73,6 +73,11 @@ in {
           an absolute path or <literal>null</literal> in which case
           <filename>~/.xmonad/xmonad.hs</filename> will not be managed
           by Home Manager.
+          </para>
+          <para>
+          If this option is set to a non-<literal>null</literal> value,
+          recompilation of xmonad outside of Home Manager (e.g. via
+          <command>xmonad --recompile</command>) will fail.
         '';
       };