diff --git a/README.dev b/README.dev
index 76b29f94c..d6c2c7b72 100644
--- a/README.dev
+++ b/README.dev
@@ -1,19 +1,77 @@
-# A test server should be running for tests
+README.dev
+==========
 
-Sample configuration (e.g. ~/.config/swh/storage.ini):
+A test server could locally be running for tests.
 
-    [main]
-    db=dbname=softwareheritage-dev
-    storage_base=/tmp/swh/storage/
+# Sample configuration
 
-Note: `storage_base` entry referenced should exist.
+In either /etc/softwareheritage/storage/storage.yml,
+~/.config/swh/storage.yml or ~/.swh/storage.yml:
 
-# Start
+```
+storage:
+  cls: local
+  args:
+    db: "dbname=softwareheritage-dev user=<user>"
+    objstorage:
+      cls: pathslicing
+      args:
+        root: /home/storage/swh-storage/
+        slicing: 0:2/2:4/4:6
+```
 
-local only:
+which means, this uses:
 
-    python3 -m swh.storage.api.server ~/.config/swh/storage.ini
+- a local storage instance whose db connection is to
+  softwareheritage-dev local instance
 
-local only but accessible from other machine:
+- the objstorage uses a local objstorage instance whose:
 
-    python3 -m swh.storage.api.server ~/.config/swh/storage.ini 0.0.0.0
+  - root path is /home/storage/swh-storage
+
+  - slicing scheme is 0:2/2:4/4:6. This means that the identifier of
+    the content (sha1) which will be stored on disk at first level
+    with the first 2 hex characters, the second level with the next 2
+    hex characters and the third level with the next 2 hex
+    characters. And finally the complete hash file holding the raw
+    content. For example: 00062f8bd330715c4f819373653d97b3cd34394c
+    will be stored at 00/06/2f/00062f8bd330715c4f819373653d97b3cd34394c
+
+Note that the 'root' path should exist on disk.
+
+
+# Run server
+
+Command:
+```
+python3 -m swh.storage.api.server ~/.config/swh/storage.yml
+```
+
+This runs a local swh-storage api at 5000 port.
+
+
+# And then what?
+
+In your upper layer (loader-git, loader-svn, etc...), you can define a
+remote storage with this snippet of yaml configuration.
+
+```
+storage:
+  cls: remote
+  args:
+    url: http://localhost:5000/
+```
+
+You could directly define a local storage with the following snippet:
+
+```
+storage:
+  cls: local
+  args:
+    db: service=swh-dev
+    objstorage:
+      cls: pathslicing
+      args:
+        root: /home/storage/swh-storage/
+        slicing: 0:2/2:4/4:6
+```