diff --git a/default.nix b/default.nix
index b22e926e..32d510a3 100644
--- a/default.nix
+++ b/default.nix
@@ -1,3 +1,6 @@
+# The `default.nix` in flake-compat reads `flake.nix` and `flake.lock` from `src` and
+# returns an attribute set of the shape `{ defaultNix, shellNix }`
+
 (import (fetchTarball https://github.com/edolstra/flake-compat/archive/master.tar.gz) {
   src = builtins.fetchGit ./.;
 }).defaultNix
diff --git a/shell.nix b/shell.nix
index db84e3d0..8b8aa5aa 100644
--- a/shell.nix
+++ b/shell.nix
@@ -1,3 +1,6 @@
+# The `default.nix` in flake-compat reads `flake.nix` and `flake.lock` from `src` and
+# returns an attribute set of the shape `{ defaultNix, shellNix }`
+
 (import (fetchTarball https://github.com/edolstra/flake-compat/archive/master.tar.gz) {
   src = builtins.fetchGit ./.;
 }).shellNix