diff --git a/doc/frequently-asked-questions.rst b/doc/frequently-asked-questions.rst
index b44988d86..999b0478f 100644
--- a/doc/frequently-asked-questions.rst
+++ b/doc/frequently-asked-questions.rst
@@ -497,24 +497,29 @@ The solution is to add it as another package to the environment:
 Quality assurance
 ~~~~~~~~~~~~~~~~~
 
-The ``haskell.lib`` library includes a number of functions for checking
-for various imperfections in Haskell packages. It’s useful to apply
-these functions to your own Haskell packages and integrate that in a
-Continuous Integration server like `hydra <https://nixos.org/hydra/>`__
-to assure your packages maintain a minimum level of quality. This
-section discusses some of these functions.
+The ``haskell.lib.compose`` library, (herein referred to as ``haskellLib``)
+includes a number of functions for checking for various imperfections in
+Haskell packages. It’s useful to apply these functions to your own Haskell
+packages and integrate that in a Continuous Integration server like `hydra
+<https://nixos.org/hydra/>`__ to assure your packages maintain a minimum level
+of quality. This section discusses some of these functions.
+
+There also exists ``haskell.lib`` with the same functionality, but with a less
+easy to compose argument ordering where the derivation being overridden comes
+before any additional arguments, for this reason ``haskell.lib.compose`` is
+preferred.
 
 failOnAllWarnings
 ^^^^^^^^^^^^^^^^^
 
-Applying ``haskell.lib.failOnAllWarnings`` to a Haskell package enables
+Applying ``haskellLib.failOnAllWarnings`` to a Haskell package enables
 the ``-Wall`` and ``-Werror`` GHC options to turn all warnings into
 build failures.
 
 buildStrictly
 ^^^^^^^^^^^^^
 
-Applying ``haskell.lib.buildStrictly`` to a Haskell package calls
+Applying ``haskellLib.buildStrictly`` to a Haskell package calls
 ``failOnAllWarnings`` on the given package to turn all warnings into
 build failures. Additionally the source of your package is gotten from
 first invoking ``cabal sdist`` to ensure all needed files are listed in
@@ -523,7 +528,7 @@ the Cabal file.
 checkUnusedPackages
 ^^^^^^^^^^^^^^^^^^^
 
-Applying ``haskell.lib.checkUnusedPackages`` to a Haskell package
+Applying ``haskellLib.checkUnusedPackages`` to a Haskell package
 invokes the
 `packunused <http://hackage.haskell.org/package/packunused>`__ tool on
 the package. ``packunused`` complains when it finds packages listed as
@@ -531,7 +536,7 @@ build-depends in the Cabal file which are redundant. For example:
 
 ::
 
-   $ nix-build -E 'let pkgs = import <nixpkgs> {}; in pkgs.haskell.lib.checkUnusedPackages {} pkgs.haskellPackages.scientific'
+   $ nix-build -E 'let pkgs = import <nixpkgs> {}; in pkgs.haskell.lib.compose.checkUnusedPackages {} pkgs.haskellPackages.scientific'
    these derivations will be built:
      /nix/store/3lc51cxj2j57y3zfpq5i69qbzjpvyci1-scientific-0.3.5.1.drv
    ...
diff --git a/doc/nixpkgs-users-guide.rst b/doc/nixpkgs-users-guide.rst
index c30cda104..eb9b149de 100644
--- a/doc/nixpkgs-users-guide.rst
+++ b/doc/nixpkgs-users-guide.rst
@@ -147,17 +147,17 @@ for hackage. You can use ``overrideSrc`` to override the source, for example:
 
 .. code:: nix
 
-   my-hledger-lib = (haskell.lib.overrideSrc haskellPackages.hledger-lib {
+   my-hledger-lib = (haskell.lib.compose.overrideSrc {
      src = /home/aengelen/dev/hledger/hledger-lib;
-   });
-   my-hledger = (haskell.lib.overrideSrc haskellPackages.hledger {
+   }) haskellPackages.hledger-lib;
+   my-hledger = (haskell.lib.compose.overrideSrc {
      src = /home/aengelen/dev/hledger/hledger;
-   }).override {
+   } haskellPackages.hledger).override {
      hledger-lib = my-hledger-lib;
    };
-   hledger-web = haskell.lib.justStaticExecutables ((haskell.lib.overrideSrc haskellPackages.hledger-web {
+   hledger-web = haskell.lib.compose.justStaticExecutables ((haskell.lib.compose.overrideSrc {
        src = /home/aengelen/dev/hledger/hledger-web;
-     })
+     } haskellPackages.hledger-web)
      .override {
        hledger = my-hledger;
        hledger-lib = my-hledger-lib;
@@ -541,17 +541,16 @@ way, or with extra environment variables. In these cases, you’ll need a
      enable: true
      shell-file: shell.nix
 
-For more on how to write a ``shell.nix`` file see the below section.
-You’ll need to express a derivation. Note that Nixpkgs ships with a
-convenience wrapper function around ``mkDerivation`` called
-``haskell.lib.buildStackProject`` to help you create this derivation in
-exactly the way Stack expects. However for this to work you need to
-disable the sandbox, which you can do by using
-``--option sandbox relaxed`` or ``--option sandbox false`` to the Nix
-command. All of the same inputs as ``mkDerivation`` can be provided. For
-example, to build a Stack project that including packages that link
-against a version of the R library compiled with special options turned
-on:
+For more on how to write a ``shell.nix`` file see the below section.  You’ll
+need to express a derivation. Note that Nixpkgs ships with a convenience
+wrapper function around ``mkDerivation`` called
+``haskell.lib.compose.buildStackProject`` to help you create this derivation in
+exactly the way Stack expects. However for this to work you need to disable the
+sandbox, which you can do by using ``--option sandbox relaxed`` or ``--option
+sandbox false`` to the Nix command. All of the same inputs as ``mkDerivation``
+can be provided. For example, to build a Stack project that including packages
+that link against a version of the R library compiled with special options
+turned on:
 
 .. code:: nix
 
@@ -559,7 +558,7 @@ on:
 
    let R = pkgs.R.override { enableStrictBarrier = true; };
    in
-   haskell.lib.buildStackProject {
+   haskell.lib.compose.buildStackProject {
      name = "HaskellR";
      buildInputs = [ R zeromq zlib ];
    }
@@ -577,7 +576,7 @@ specified in ``stack.yaml`` (only works with Stack >= 1.1.3):
 
    let R = pkgs.R.override { enableStrictBarrier = true; };
    in
-   haskell.lib.buildStackProject {
+   haskell.lib.compose.buildStackProject {
      name = "HaskellR";
      buildInputs = [ R zeromq zlib ];
      inherit ghc;