diff --git a/README.md b/README.md
index 9c3730c85e852e40f421b8c9e305143984b785d8..188382f0e7d40c2102f6a56e5be9973da14b1010 100644
--- a/README.md
+++ b/README.md
@@ -1,32 +1,49 @@
-# Portail Data documentation
-
-## Commands
-
-* `mkdocs new [dir-name]` - Create a new project.
-* `mkdocs serve` - Start the live-reloading docs server.
-* `mkdocs build` - Build the documentation site.
-* `mkdocs help` - Print this help message.
-
-## Setting files hierarchy
-    inside mkdocs.yml use the key nav: to configure the md files hierarchy
-
-    nav:
-        - Home: index.md
-        - Architecture Guide:
-            - Admin-gui: architecture/admin-gui.md
-            - Admin-tools: architecture/admin-tools.md
-            - Api-gateway: architecture/api-gateway.md
-            - CMS: architecture/cms.md
-            - Monitoring: architecture/monitoring.md
-            - Web-app: architecture/web-app.md
-            - Service:
-                - authentification: architecture/service/autentification.md
-                - Elasticsearch:
-                    - Indexer: architecture/service/elasticsearch/indexer.md
-
-## Project layout
-
-    mkdocs.yml    # The main file and configuration file.
-    docs/
-        index.md  # The documentation homepage.
-        ...       # Other markdown pages, images and other files.
\ No newline at end of file
+# data.grandlyon.com Developer Guide
+
+This documentation is fully written in Markdown. [MkDocs](https://www.mkdocs.org/) is used as well, so as to generate a beautiful static site out of this documentation.
+
+## MkDocs configuration
+
+MkDocs can be configured by editing the `mkdocs.yml` file. We refer the user to the [official MkDocs documentation](https://www.mkdocs.org/user-guide/) for futher information.
+
+## Running MkDocs with virtualenv
+
+The following commands allows one to setup a Python virtual environment, capable of running `mkdocs`:
+
+```bash
+$ python3 -mvenv venv
+$ source venv/bin/activate
+$ pip install -r requirements.txt
+```
+
+This project can then be built by issuing the following command:
+
+```bash
+$ mkdocs build
+```
+
+A development server featuring live refresh can be started as follows:
+
+```bash
+$ mkdocs serve
+```
+
+
+## Running MkDocs with Docker (recommended)
+
+The provided `Dockerfile` and a `docker-compose.yml` file allow one to build and run this project with Docker.
+
+### Build
+```bash
+$ docker-compose build
+```
+
+### Run
+```bash
+$ docker-compose up [-d]
+```
+
+### Build 'n' Run
+```bash
+$ docker-compose up --build [-d]
+```