diff --git a/README.md b/README.md
index d389af3..3b04020 100644
--- a/README.md
+++ b/README.md
@@ -30,7 +30,6 @@ format=columns
 
 The file is in `~/.config/pip/` in Linux/FreeBSD and `~/Library/Application Support/pip/pip.conf` in MacOS.
 
-
 ---
 
 ## 2. Installation
@@ -38,12 +37,16 @@ The file is in `~/.config/pip/` in Linux/FreeBSD and `~/Library/Application Supp
 Download and install (`USERNAME` is your account on bitbucket):
 
 ```bash
+cd ~
 git clone https://USERNAME@bitbucket.org/USERNAME/perguntations.git
 cd perguntations
 npm install
 pip3 install .
 ```
 
+Here, the repository is installed in the user home directory.
+You may wish to adjust to somewhere else.
+
 The command `npm` installs the javascript libraries and `pip3` installs the
 python webserver.
 This will also automatically install the python dependencies required.
@@ -64,8 +67,6 @@ case).
 mkdir -p ~/.local/share/certs
 ```
 
-### Selfsigned certificates
-
 Self-signed certificates are not certified by a recognised authority and
 browsers will complain that the certificate is not trusted.
 
@@ -74,36 +75,9 @@ cd ~/.local/share/certs
 openssl req -x509 -newkey rsa:4096 -keyout privkey.pem -out cert.pem -days 365 -nodes
 ```
 
-### LetsEncript (FreeBSD)
-
-Generating certificates for a public server (FreeBSD) requires a registered
-domain with fixed IP.
-
-```sh
-sudo pkg install py27-certbot                   # FreeBSD
-sudo service pf stop                            # disable pf firewall (FreeBSD)
-sudo certbot certonly --standalone -d www.example.com
-sudo service pf start                           # enable pf firewall
-```
-
-Certificates are saved in `/usr/local/etc/letsencrypt/live/www.example.com/`.
-Copy them to the `certs` directory and change permissions:
-
-```sh
-chmod 400 cert.pem privkey.pem
-```
-
-Certificate renewals can be done as follows:
-
-```sh
-sudo service pf stop   # shutdown firewall
-sudo certbot renew
-sudo service pf start  # start firewall
-```
-
-Again, copy certificate files `privkey.pem` and `cert.pem` to the `certs`
-directory.
-
+To have a true certificate, like the ones issued by LetsEncrypt, the host
+must have a registered domain name.
+See instructions for FreeBSD at the end of this page.
 
 ---
 
@@ -115,29 +89,49 @@ as a template for your own tests and questions.
 To run the demonstration test you need to initialize the database using one of
 the following methods:
 
-```.bash
-cd demo
+```bash
+cd ~/perguntations/demo
 
 initdb students.csv             # initialize from a CSV file
 initdb --admin                  # only adds the administrator account
 initdb --add 123 "Asterix Gaules"  # add one student
+```
+
+This will create or update a `students.db` file that contains a sqlite3
+database.
+The database stores user passwords, and grades of the tests submitted by the
+students.
+
+The actual tests are stored in JSON files in the following directory:
 
+```bash
 mkdir ans                       # directory where the student tests are saved
+```
+
+A test is specified in a single `yaml` file.
+The demo already includes one:
+
+```bash
+$EDITOR tutorial.yaml           # edit test configuration
+```
 
-$EDITOR test-tutorial.yaml      # edit test configuration
+To start the server with this test run:
 
-perguntations --help            # get help
+```bash
 perguntations tutorial.yaml     # run demo test
 ```
 
+Several options are available, run `perguntations --help` for a list.
+
 The server listens on port 8443 of all IPs of all network interfaces.
 Open the browser at `http://127.0.0.1:8443/` and login as user number `0`
 (administrator) and choose any password. The administrator is redirected to the
 administration page that shows all the students and their state.
 
 1. Authorize students by clicking the checkboxes.
-2. Open a different browser at `http://127.0.0.1:8443/` and login as one of the
-authorized students. Answer the questions and submit.
+2. Open a different browser (or exit administrator) at `http://127.0.0.1:8443/`
+and login as one of the authorized students.
+Answer the questions and submit. You should get a grade at the end.
 
 The server can be stoped from the terminal with `^C`.
 
@@ -192,6 +186,36 @@ Optionally, to activate pf on boot, edit `rc.conf`:
     pflog_flags=""
     pflog_logfile="/var/log/pflog"
 
+## Generating certificates with LetsEncript (FreeBSD)
+
+Generating certificates for a public server (FreeBSD) requires a registered
+domain with fixed IP.
+
+```sh
+sudo pkg install py27-certbot                   # FreeBSD
+sudo service pf stop                            # disable pf firewall (FreeBSD)
+sudo certbot certonly --standalone -d www.example.com
+sudo service pf start                           # enable pf firewall
+```
+
+Certificates are saved in `/usr/local/etc/letsencrypt/live/www.example.com/`.
+Copy them to the `certs` directory and change permissions:
+
+```sh
+chmod 400 cert.pem privkey.pem
+```
+
+Certificate renewals can be done as follows:
+
+```sh
+sudo service pf stop   # shutdown firewall
+sudo certbot renew
+sudo service pf start  # start firewall
+```
+
+Again, copy certificate files `privkey.pem` and `cert.pem` to the `certs`
+directory.
+
 
 ## Troubleshooting
 
--
libgit2 0.21.2