diff --git a/README.md b/README.md
new file mode 100644
index 0000000..24705ba
--- /dev/null
+++ b/README.md
@@ -0,0 +1,21 @@
+# NixOS config
+
+NixOS configurations for a number of my machines.
+
+I use home-manager to manage my dotfiles.
+
+## Layout
+
+`machines/` has a folder for each machine (identified by hostname) with its
+`configuration.nix` and `hardware-configuration.nix`. Modules specific to each machine
+also go in their respective directories.
+
+Config values that are common to all my machines are in `common.nix`.
+
+`scripts/` contains shell scripts and small, trivial utilities that are intended to be
+invoked on the command line.
+
+`modules/` contains NixOS modules that configure things like git, ssh, my window manager
+and my editor.
+
+`overlays/` contains nix overlays.