diff --git a/README.asciidoc b/README.asciidoc
index 1dd5d14a..f69edc84 100644
--- a/README.asciidoc
+++ b/README.asciidoc
@@ -244,18 +244,36 @@ Just running *kak* launch a new kak session with a client on local terminal.
  * `-clear`: clear dead sessions socket files
  * `-ro`: prevent modifications to all buffers from being saved to disk
 
-At startup, if `-n` is not specified, Kakoune will try to source the file
-`../share/kak/kakrc` relative to the kak binary. This kak file will then try
-to recursively source any files in `$XDG_CONFIG_HOME/kak/autoload` (with
-`$XDG_CONFIG_HOME` defaulting to `$HOME/.config`, and falling back to
-`../share/kak/autoload/` if that autoload directory does not exists), then
-`../share/kak/kakrc.local` if it exists, and finally `$XDG_CONFIG_HOME/kak/kakrc`.
+Configuration
+^^^^^^^^^^^^^
 
-That leads to the following behaviour: by default, with no user autoload
-directory, the system wide autoload directory is used, once the user wants
-control on autoloading, they can create an autoload directory and eventually
-symlink individual scripts, or the whole system wide autoload directory. They
-can as well add any new scripts not provided with Kakoune.
+There are two directories containing Kakoune's scripts:
+
+* `runtime`: located in `../share/kak/` relative to the `kak` binary
+  contains the system scripts, installed with Kakoune.
+* `userconf`: located in `$XDG_CONFIG_HOME/kak/`, which defaults
+  to `$HOME/.config/kak/` on most systems, containing the user
+  configuration.
+
+When `-n` is not specified, Kakoune will load its startup script located
+at `${runtime}/kakrc` relative to the `kak` binary. This startup script
+is responsible for loading the user configuration.
+
+First, Kakoune will search recursively for `.kak` files in the `autoload`
+directory. It will first look for an `autoload` directory at
+`${userconf}/autoload` and will fallback to `${runtime}/autoload` if
+it does not exists.
+
+Once all those files are loaded, Kakoune will try to source
+`${runtime}/kakrc.local` which is expected to contain distribution provided
+configuration.
+
+And finally, the user configuration will be loaded from `${userconf}/kakrc`.
+
+NOTE: If you create a user `autoload` directory in `${userconf}/autoload`,
+the system one at `${runtime}/autoload` will not be loaded anymore. You can
+add a symbolic link to it (or to individual scripts) inside
+`${userconf}/autoload` to keep loading system scripts.
 
 Basic Interaction
 -----------------