diff --git a/nixos/doc/manual/configuration/customizing-packages.xml b/nixos/doc/manual/configuration/customizing-packages.xml
index 6ee7a95dc6fa..8aa01fb57a09 100644
--- a/nixos/doc/manual/configuration/customizing-packages.xml
+++ b/nixos/doc/manual/configuration/customizing-packages.xml
@@ -42,29 +42,30 @@ construction, so without them,
 elements.)</para>
 
 <para>Even greater customisation is possible using the function
-<varname>overrideDerivation</varname>.  While the
+<varname>overrideAttrs</varname>.  While the
 <varname>override</varname> mechanism above overrides the arguments of
-a package function, <varname>overrideDerivation</varname> allows
-changing the <emphasis>result</emphasis> of the function.  This
-permits changing any aspect of the package, such as the source code.
+a package function, <varname>overrideAttrs</varname> allows
+changing the <emphasis>attributes</emphasis> passed to <literal>mkDerivation</literal>.
+This permits changing any aspect of the package, such as the source code.
 For instance, if you want to override the source code of Emacs, you
 can say:
 
 <programlisting>
-environment.systemPackages =
-  [ (pkgs.lib.overrideDerivation pkgs.emacs (attrs: {
-      name = "emacs-25.0-pre";
-      src = /path/to/my/emacs/tree;
-    }))
-  ];
+environment.systemPackages = [
+  (pkgs.emacs.overrideAttrs (oldAttrs: {
+    name = "emacs-25.0-pre";
+    src = /path/to/my/emacs/tree;
+  }))
+];
 </programlisting>
 
-Here, <varname>overrideDerivation</varname> takes the Nix derivation
+Here, <varname>overrideAttrs</varname> takes the Nix derivation
 specified by <varname>pkgs.emacs</varname> and produces a new
 derivation in which the original’s <literal>name</literal> and
 <literal>src</literal> attribute have been replaced by the given
-values.  The original attributes are accessible via
-<varname>attrs</varname>.</para>
+values by re-calling <literal>stdenv.mkDerivation</literal>.
+The original attributes are accessible via the function argument,
+which is conventionally named <varname>oldAttrs</varname>.</para>
 
 <para>The overrides shown above are not global.  They do not affect
 the original package; other packages in Nixpkgs continue to depend on
diff --git a/nixos/modules/config/debug-info.nix b/nixos/modules/config/debug-info.nix
index 671a59f52f6d..49991d22a933 100644
--- a/nixos/modules/config/debug-info.nix
+++ b/nixos/modules/config/debug-info.nix
@@ -17,12 +17,10 @@ with lib;
         where tools such as <command>gdb</command> can find them.
         If you need debug symbols for a package that doesn't
         provide them by default, you can enable them as follows:
-        <!-- FIXME: ugly, see #10721 -->
         <programlisting>
         nixpkgs.config.packageOverrides = pkgs: {
-          hello = pkgs.lib.overrideDerivation pkgs.hello (attrs: {
-            outputs = attrs.outputs or ["out"] ++ ["debug"];
-            buildInputs = attrs.buildInputs ++ [&lt;nixpkgs/pkgs/build-support/setup-hooks/separate-debug-info.sh>];
+          hello = pkgs.hello.overrideAttrs (oldAttrs: {
+            separateDebugInfo = true;
           });
         };
         </programlisting>
diff --git a/nixos/modules/services/editors/emacs.xml b/nixos/modules/services/editors/emacs.xml
index bcaa8b8df3d8..e03f6046de8e 100644
--- a/nixos/modules/services/editors/emacs.xml
+++ b/nixos/modules/services/editors/emacs.xml
@@ -356,14 +356,14 @@ https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides
         <programlisting><![CDATA[
 { pkgs ? import <nixpkgs> {} }:
 let
-  myEmacs = pkgs.lib.overrideDerivation (pkgs.emacs.override {
+  myEmacs = (pkgs.emacs.override {
     # Use gtk3 instead of the default gtk2
     withGTK3 = true;
     withGTK2 = false;
-  }) (attrs: {
+  }).overrideAttrs (attrs: {
     # I don't want emacs.desktop file because I only use
     # emacsclient.
-    postInstall = attrs.postInstall + ''
+    postInstall = (attrs.postInstall or "") + ''
       rm $out/share/applications/emacs.desktop
     '';
   });