diff --git a/default.nix b/default.nix
index cecb5579a..a8a7ba1c8 100644
--- a/default.nix
+++ b/default.nix
@@ -1,4 +1,23 @@
 let
+  # sources.nix contains information about which versions of some of our
+  # dependencies we should use.  since we use it to pin nixpkgs and the PyPI
+  # package database, roughly all the rest of our dependencies are *also*
+  # pinned - indirectly.
+  #
+  # sources.nix is managed using a tool called `niv`.  as an example, to
+  # update to the most recent version of nixpkgs from the 21.11 maintenance
+  # release, in the top-level tahoe-lafs checkout directory you run:
+  #
+  #   niv update nixpkgs-21.11
+  #
+  # or, to update the PyPI package database -- which is necessary to make any
+  # newly released packages visible -- you likewise run:
+  #
+  #   niv update pypi-deps-db
+  #
+  # niv also supports chosing a specific revision, following a different
+  # branch, etc.  find complete documentation for the tool at
+  # https://github.com/nmattia/niv
   sources = import nix/sources.nix;
 in
 {