diff --git a/doc/functions.xml b/doc/functions.xml
index 39010f8ab14..e2bc751e140 100644
--- a/doc/functions.xml
+++ b/doc/functions.xml
@@ -88,6 +88,13 @@ in ...</programlisting>
 <section xml:id="sec-pkg-overrideDerivation">
   <title>&lt;pkg&gt;.overrideDerivation</title>
 
+  <warning>
+    <para>Do not use this function in Nixpkgs. Because it breaks
+    package abstraction and doesn’t provide error checking for
+    function arguments, it is only intended for ad-hoc customisation
+    (such as in <filename>~/.nixpkgs/config.nix</filename>).</para>
+  </warning>
+
   <para>
     The function <varname>overrideDerivation</varname> is usually available for all the
     derivations in the nixpkgs expression (<varname>pkgs</varname>).