diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6088706
--- /dev/null
+++ b/README.md
@@ -0,0 +1,37 @@
+# Geoffrey Frogeye's dotfiles
+
+This repo holds most of my systems configuration.
+It is built on top of the Nix ecosystem
+
+## Directory structure
+
+- `os`, `hm`, `nod`: Re-usable configuration for [NixOS](https://nixos.org/), [home-manager](https://github.com/nix-community/home-manager/#home-manager-using-nix), [Nix-on-Droid](https://github.com/nix-community/nix-on-droid#nix-on-droid) respectively
+    - `<module-name>`: Module. Used to separate configuration in separate logical units.
+        - `default.nix`: Entrypoint for that module. Contains Nix configuration for the module.
+        - `<other file>`: Extra files: scripts to be installed, or ... whatever.
+    - `default.nix`: Entrypoint for that system. Import all the modules.
+    - `<other file>`: Files non-conforming to the structure above because I'm hurrying to have everything working before cleaning.
+- `dk`: Re-usable configuration for [disko](https://github.com/nix-community/disko#disko---declarative-disk-partitioning)
+    - `<name>.nix`: Partitionning scheme configuration. Don't assume a specific context, it will be imported as Disko and NixOS config.
+- `options.nix`: Definition of options exposed to all systems (even though if not relevant for all, it's for simplicity sake).
+- `<profile-name>` (e.g. `curacao`): Configurations for my different devices
+    - `options.nix`: Common options configuration. Don't assume a specific context (for reasons unclear, I'm sure I can do something with that).
+    - `hardware.nix`: NixOS configuration for that specific device.
+    - `dk.nix`: Partitionning configuration. Import a top-level `dk` scheme, adding disks ids and other configuration required.
+    - `os.nix`, `hm.nix`, `nod.nix`: Entrypoint for the device/system configuration. Imports the above files (last two only for NixOS) and contains configuration specific to this combination.
+- `<profile-name>_<media>` (e.g. `pindakaas_sd`): Alternate configuration for a device. Used to test a configuration without altering the "main" one.
+    - `options.nix`: Same as above. Can be a symlink.
+    - `hardware.nix`: Same as above. Should be a symlink.
+    - `dk.nix`: Same as above. Should not be a symlink.
+    - `os.nix`, `hm.nix`, `nod.nix`: Same as above. Should not be a symlink.
+
+## Scripts
+
+They all have a `-h` flag.
+Except `add_channels.sh`, which should be removed as soon as I migrate to Flakes.
+
+## Extensions
+
+There's some things I'm not putting in this public repo: work-related things, and other sensitive things that probably shouldn't be public.
+Those are stored in extensions, i.e. repos with a similar structure to this one, and ultimately importing things from it.
+This is why you might see options not being seemingly used.
diff --git a/build_os.sh b/build_os.sh
index 7c15d89..2c655d9 100755
--- a/build_os.sh
+++ b/build_os.sh
@@ -8,6 +8,7 @@ SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
 # Parse arguments
 function help {
     echo "Usage: $0 [-h|-v|-b] profile"
+    echo "Build NixOS configuration on the local machine."
     echo
     echo "Arguments:"
     echo "  profile: OS/disk profile to use"
diff --git a/curacao/os.nix b/curacao/os.nix
index fd60a8c..3bd283d 100644
--- a/curacao/os.nix
+++ b/curacao/os.nix
@@ -4,7 +4,7 @@
     ../os
     ./options.nix
     ./hardware.nix
-    ./disko.nix
+    ./dk.nix
   ];
 
   networking.hostName = "curacao";
diff --git a/curacao_usb/disko.nix b/curacao_usb/dk.nix
similarity index 100%
rename from curacao_usb/disko.nix
rename to curacao_usb/dk.nix
diff --git a/curacao_usb/os.nix b/curacao_usb/os.nix
index 32b2211..59d3b3d 100644
--- a/curacao_usb/os.nix
+++ b/curacao_usb/os.nix
@@ -4,7 +4,7 @@
     ../os
     ../curacao/options.nix
     ../curacao/hardware.nix
-    ./disko.nix
+    ./dk.nix
   ];
 
   networking.hostName = "curacao_usb";
diff --git a/install_os.sh b/install_os.sh
index 87bf1b3..8b642f6 100755
--- a/install_os.sh
+++ b/install_os.sh
@@ -8,13 +8,14 @@ SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
 # Parse arguments
 function help {
     echo "Usage: $0 [-h|-e] profile"
+    echo "Install NixOS on a device."
     echo
     echo "Arguments:"
     echo "  profile: OS/disk profile to use"
     echo
     echo "Options:"
     echo "  -h: Display this help message."
-    echo "  -e: Erase the disk. This can be used in case the wanted partition scheme doesn't match."
+    echo "  -e: Erase the disk. For cases where the partition scheme doesn't match the existing one."
 }
 
 disko_mode=mount
@@ -49,7 +50,7 @@ then
     echo "Profile not found."
 fi
 
-disko_config="${profile_dir}/disko.nix"
+disko_config="${profile_dir}/dk.nix"
 if [ ! -f "$disko_config" ]
 then
     echo "Disk configuration not found."
diff --git a/pindakaas/os.nix b/pindakaas/os.nix
index e0e1f93..9a992d4 100644
--- a/pindakaas/os.nix
+++ b/pindakaas/os.nix
@@ -3,7 +3,7 @@
   imports = [
     ../os
     ./hardware.nix
-    ./disko.nix
+    ./dk.nix
     ./options.nix
   ];
 
diff --git a/pindakaas_sd/disko.nix b/pindakaas_sd/dk.nix
similarity index 100%
rename from pindakaas_sd/disko.nix
rename to pindakaas_sd/dk.nix
diff --git a/pindakaas_sd/os.nix b/pindakaas_sd/os.nix
index 351874c..75219ff 100644
--- a/pindakaas_sd/os.nix
+++ b/pindakaas_sd/os.nix
@@ -4,7 +4,7 @@
     ../os
     ../pindakaas/options.nix
     ../pindakaas/hardware.nix
-    ./disko.nix
+    ./dk.nix
   ];
 
   networking.hostName = "pindakaas_sd";