diff --git a/README.md b/README.md
index 92275f5..1640521 100644
--- a/README.md
+++ b/README.md
@@ -2,8 +2,30 @@
 
 **I'll be there, 2** is an oversimplified application to register attendees at a conference or event.
 
+Basic workflow:
+- if you want (not mandatory), login with your user; to create a new user, simply choose a username and a password. Benefit of logging in: only you or admins can edit/delete your entries.
+- pick a date
+- choose the name of a new group
+- write your name
+- rinse and repeat
+
+It's recommended to login with username '''admin''' and password '''ibt2''', go to your personal page and change the password, if you've just installed ibt2.
+
 ## Run, develop and debug
 
+To install it:
+``` bash
+wget https://bootstrap.pypa.io/get-pip.py
+sudo python get-pip.py
+sudo pip install tornado
+sudo pip install pymongo
+sudo pip install python-dateutil
+git clone https://github.com/raspibo/ibt2
+cd ibt2
+```
+
+Installation of [Node.js](https://nodejs.org/en/download/) and npm is left as an exercise to the reader.
+
 To run it:
 ``` bash
 # install dependencies (one time only)
@@ -26,17 +48,28 @@ npm run devserver &
 
 # serve with hot reload at localhost:8080
 npm run dev
+
+# only when the devserver is running, you can also run the testsuite
+python ./tests/ibt2_tests.py
 ```
 
+
+Development
+===========
+
+See the *docs/DEVELOPMENT.md* file for more information about how to contribute.
+
+
 Technological stack
 ===================
 
 - [VueJS](https://vuejs.org/) for the webApp
 - [Vue Material](https://vuematerial.github.io/) for the UI components
+- [vue Datepicker](https://github.com/charliekassel/vuejs-datepicker) for the datepicker
 - [Tornado web](http://www.tornadoweb.org/) as web server
 - [MongoDB](https://www.mongodb.org/) to store the data
 
-The web part is incuded; you need to install Tornado, MongoDB and the pymongo module on your system (no configuration needed).
+The web part is incuded; you need to install Node.js, Tornado, MongoDB and the pymongo module on your system (no configuration needed).
 
 
 License and copyright
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
new file mode 100644
index 0000000..f194c1e
--- /dev/null
+++ b/docs/DEVELOPMENT.md
@@ -0,0 +1,49 @@
+ibt2 development
+================
+
+Paths
+=====
+
+Webapp
+------
+
+These are the paths you see in the browser (VueJS does client-side routing: no request is issued to the web server, during navigation, if not for fetching data and issuing commands):
+
+- / - home; will redirect to the entry for today
+- /#/day/:day - show groups for the given date (in yyyy-mm-dd format)
+- /#/user/ - list of all users (only visible by admins)
+- /#/user/:user - show setting for the give user ID
+
+Web server
+----------
+
+Database layout
+===============
+
+Information are stored in MongoDB.  Whenever possible, object are converted into native ObjectId.
+
+attendees collection
+--------------------
+
+
+Code layout
+===========
+
+The code is so divided:
+
+    +- ibt2.py - the Tornado Web server
+
+
+Coding style and conventions
+----------------------------
+
+It's enough to be consistent within the document you're editing.
+
+I suggest four spaces instead of tabs for all the code: Python (**mandatory**), JavaScript, HTML and CSS.
+
+Python code documented following the [Sphinx](http://sphinx-doc.org/) syntax.
+
+
+not-so-FAQs
+===========
+