diff --git a/README.md b/README.md
index 95498acd5b7dfc321ba639b1f56386f2f458b19b..5747508cbf467bad42cbd30f50c495f063f52efa 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,37 @@
 # JASS
 
-## HOWTO
+## setup
 
-To run the server, please execute the following from the root directory:
+The main requirement is **python 3**. To setup the server in a dedicated virtualenv (you need **virtualenv**), please execute the following from the root directory, once you have cloned the repository:
 
 ```
+virtualenv venv
+. venv/bin/activate
 pip3 install -r requirements.txt
-python3 -m swagger_server
+# you can quit the virtualenv with
+deactivate
 ```
 
-and open your browser to here:
+## run
+
+```
+# activate the virtualenv
+. venv/bin/activate
+# run the server, [CTRL+C] to quit
+python -m swagger-server
+# you can quit the virtualenv with
+deactivate
+```
+
+## browse
+
+### for end users
+
+TODO
+
+### for developers
+
+The Swagger UI is there:
 
 ```
 http://localhost:8080/ui/
@@ -21,6 +43,8 @@ The Swagger definition for this server's API lives here:
 http://localhost:8080/swagger.json
 ```
 
+# tests
+
 To launch the integration tests, use tox:
 ```
 sudo pip install tox