diff --git a/nixos/doc/manual/development/option-types.xml b/nixos/doc/manual/development/option-types.xml
index 5a6dae6e991..9827615349d 100644
--- a/nixos/doc/manual/development/option-types.xml
+++ b/nixos/doc/manual/development/option-types.xml
@@ -21,16 +21,6 @@
   </para>
 
   <variablelist>
-   <varlistentry>
-    <term>
-     <varname>types.attrs</varname>
-    </term>
-    <listitem>
-     <para>
-      A free-form attribute set.
-     </para>
-    </listitem>
-   </varlistentry>
    <varlistentry>
     <term>
      <varname>types.bool</varname>
@@ -64,6 +54,24 @@
      </para>
     </listitem>
    </varlistentry>
+   <varlistentry>
+    <term>
+     <varname>types.attrs</varname>
+    </term>
+    <listitem>
+     <para>
+      A free-form attribute set.
+      <warning><para>
+       This type will be deprecated in the future because it doesn't recurse
+       into attribute sets, silently drops earlier attribute definitions, and
+       doesn't discharge <literal>lib.mkDefault</literal>, <literal>lib.mkIf
+       </literal> and co. For allowing arbitrary attribute sets, prefer
+       <literal>types.attrsOf types.anything</literal> instead which doesn't
+       have these problems.
+      </para></warning>
+     </para>
+    </listitem>
+   </varlistentry>
   </variablelist>
 
   <para>