diff --git a/README.md b/README.md
index 8390b74..2726451 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,44 @@
 # cardano.nix
 
-Collection of Cardano related NixOS modules, with a special focus on:
+Collection of Cardano related Nix packages and NixOS modules, with a special focus on:
 
-- autogenerated documentation
-- comprehensive (NixOS) tests
-- an homogeneous module interface
+- autogenerated [documentation](https://mlabs-haskell.github.io/cardano.nix/)
+- vm integration [tests](tests/)
+- homogeneous [module interface](https://mlabs-haskell.github.io/cardano.nix/reference/module-options/globals/)
 
-## Shell
+### Read the [Documentation](https://mlabs-haskell.github.io/cardano.nix/)
 
-`cardano.nix` provides a shell that includes some useful aliases:
+## Setup
 
-- `fmt` formats the entire repository using [treefmt](https://github.com/numtide/treefmt)
-- `build-all` builds all the flake's outputs using [devour-flake](https://github.com/srid/devour-flake)
-- `check` simply stands for `nix flake check`
+Install nix and enable flakes, eg. with [Determinate nix installer](https://github.com/DeterminateSystems/nix-installer).
 
-A `.envrc` is also provided, using [direnv]() and [nix-direnv](https://github.com/nix-community/nix-direnv) is highly suggested.
+Use the project's binary cache to skip builds. Edit `/etc/nix/nix.conf` (or related settings in NixOS config) and merge the new values separated by spaces into the options:
 
-## Documentation
+```
+substituters = ... https://cache.staging.mlabs.city/cardano-nix
+trusted-public-keys = ... cardano-nix:BQ7QKgoQQAuL3Kh6pfIJ8oxrihUbUSxf6tN9SxyW608=
+```
 
-Rendered [documentation](https://mlabs-haskell.github.io/cardano.nix/).
+Don't edit `~/.config/nix/nix.conf` in your home directory. Don't add users to `trusted-users` because it is [insecure](https://nixos.org/manual/nix/stable/command-ref/conf-file.html?highlight=trusted-user#conf-trusted-users).
+
+### Development Shell
+
+`cardano.nix` provides a devshell that includes some useful tools and aliases:
+
+```
+❯ nix develop
+...
+❄️ Welcome to the cardano.nix devshell ❄️
+...
+[Tools]
+
+  build-all  - Build all the checks
+  check      - Alias of `nix flake check`
+  fmt        - Format the source tree
+...
+```
+
+A `.envrc` is also provided, using [direnv]() and [nix-direnv](https://github.com/nix-community/nix-direnv) is suggested.
 
 ## License information
 
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 1dd129e..b603232 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -1,4 +1,4 @@
-site_name: Cardano.nix
+site_name: cardano.nix
 site_description: Nix packages and NixOS modules for the Cardano ecosystem
 site_url: https://github.com/mlabs-haskell/cardano.nix
 
diff --git a/shell/default.nix b/shell/default.nix
index 8aa8496..a7a79a6 100644
--- a/shell/default.nix
+++ b/shell/default.nix
@@ -12,7 +12,7 @@
       devshell = {
         name = "cardano.nix";
         motd = ''
-          ❄️ Welcome to the {14}{bold}cardano.nix{reset}'s shell ❄️
+          ❄️ Welcome to the {14}{bold}cardano.nix{reset} devshell ❄️
           $(type -p menu &>/dev/null && menu)
         '';
       };