diff --git a/BUGS.md b/BUGS.md
index 7136d93..c8aa261 100644
--- a/BUGS.md
+++ b/BUGS.md
@@ -1,7 +1,6 @@
 
 # BUGS
 
-- usar npm para instalar javascript
 - impedir os eventos copy/paste. alunos usam isso para trazer codigo ja feito nos computadores. Obrigar a fazer reset? fazer um copy automaticamente?
 - a revisao do teste não mostra as imagens.
 - melhorar o botao de autorizar (desliga-se), usar antes um botao?
@@ -10,13 +9,13 @@ ou usar push (websockets?)
 - pymips: nao pode executar syscalls do spim.
 - perguntas checkbox [right,wrong] com pelo menos uma opção correcta.
 - questions.py textarea has a abspath which does not make sense! why is it there? not working for perguntations, but seems to work for aprendizations
-- submissao faz um post ajax.
 - eventos unfocus?
 - servidor nao esta a lidar com eventos scroll/resize. ignorar?
 - Test.reset_answers() unused.
 
 # TODO
 
+- submissao fazer um post ajax?
 - fazer package para instalar perguntations com pip.
 - adicionar opcao para eliminar um teste em curso.
 - gerar teste qd o prof autoriza? melhor nao, pode apagar o teste em curso. gerar previamente e manter uma pool de testes gerados?
@@ -63,6 +62,7 @@ ou usar push (websockets?)
 
 # FIXED
 
+- usar npm para instalar javascript
 - se aluno entrar com l12345 rebenta. numa funcao get_... ver imagem no ipad
 - no test3 está contar 1.0 valores numa pergunta do tipo info? acontece para type: info, e não para type: information
 - default correct in checkbox must be 1.0, so that the pairs (right,wrong) still work with `correct` left undefined.
diff --git a/README.md b/README.md
index 3b04020..4c4b660 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,24 @@
-# README #
+    # README #
 
-1. [Installation](#installation)
-2. [Running a demo](#running-a-demo)
-3. [Troubleshooting](#troubleshooting)
+[Requirements](#requirements)
+[Installation](#installation)
+[Setup](#setup)
+[Running a demo](#running-a-demo)
+[Running on lower ports](#running-on-lower-ports)
+[Troubleshooting](#troubleshooting)
 
 ---
 
-## 1. Requirements
+## Requirements
 
 The webserver is a python application that requires `>=python3.6` and `pip` to be
 installed. `npm` (Node package management) is also necessary to install the
 javascript libraries.
 
 ```bash
-sudo apt install python3 python3-pip npm   # debian, ubuntu, mint, ...
+sudo apt install python3 python3-pip python3-setuptools npm          # Ubuntu
 sudo pkg install python36 py36-sqlite3 py36-pip py36-setuptools npm  # FreeBSD
-sudo port install python37 py37-pip py37-setuptools npm6  # MacOS
+sudo port install python37 py37-pip py37-setuptools npm6             # MacOS
 ```
 
 The file `pip.conf` should be configured to the following:
@@ -28,11 +31,12 @@ user=yes
 format=columns
 ```
 
-The file is in `~/.config/pip/` in Linux/FreeBSD and `~/Library/Application Support/pip/pip.conf` in MacOS.
+This file is usually in `~/.config/pip/` in Linux and FreeBSD. In MacOS it's in
+`~/Library/Application Support/pip/`.
 
 ---
 
-## 2. Installation
+## Installation
 
 Download and install (`USERNAME` is your account on bitbucket):
 
@@ -49,26 +53,27 @@ 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.
+This will also install any required dependencies.
 
 ---
 
-## 3 Setup
+## Setup
 
-The server will run an https server and requires valid certificates.
-To generate certificates, there are two possibilities: public server with
-static IP address or a private server on a local network.
+The server will run a `https` server and requires valid certificates.
+There are two possibilities to generate the certificates:
+
+- public server with static IP address and registered domain name;
+- private server on a local network isolated from the internet.
 
 Certificates must be saved in the `$XDG_DATA_HOME` path if defined in the
-environment, otherwise in `~/.local/share/certs` (I will assume the latter
-case).
+environment, otherwise in `~/.local/share/certs` (I will assume the latter).
 
 ```bash
 mkdir -p ~/.local/share/certs
 ```
 
 Self-signed certificates are not certified by a recognised authority and
-browsers will complain that the certificate is not trusted.
+browsers will complain that the certificate is not trusted. That's ok.
 
 ```bash
 cd ~/.local/share/certs
@@ -92,33 +97,28 @@ the following methods:
 ```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
+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 database stores user passwords and grades (but not the actual tests).
 
-The actual tests are stored in JSON files in the following directory:
+The complete tests are stored in JSON files in the following directory:
 
 ```bash
-mkdir ans                       # directory where the student tests are saved
+mkdir ans                           # directory where the tests will be saved
 ```
 
 A test is specified in a single `yaml` file.
-The demo already includes one:
+The demo already includes the `tutorial.yaml` that you can play with.
 
-```bash
-$EDITOR tutorial.yaml           # edit test configuration
-```
-
-To start the server with this test run:
+Start the server and run this test:
 
 ```bash
-perguntations tutorial.yaml     # run demo test
+perguntations tutorial.yaml         # run demo test
 ```
 
 Several options are available, run `perguntations --help` for a list.
@@ -135,13 +135,15 @@ Answer the questions and submit. You should get a grade at the end.
 
 The server can be stoped from the terminal with `^C`.
 
-## Running on lower ports 80 or 443
+---
+
+## Running on lower ports
 
 Ports 80 and 443 are reserved for the root user and and this software **should
 NOT be run as root**.
-Instead, the firewall should be configured to forward tcp traffic from port 443
-to 8443 where the server is listening.
-The details depend on the operating system.
+Instead, tcp traffic can be forwarded from port 443 to 8443 where the server is
+listening.
+The details depend on the operating system/firewall.
 
 ### debian:
 
@@ -216,6 +218,7 @@ sudo service pf start  # start firewall
 Again, copy certificate files `privkey.pem` and `cert.pem` to the `certs`
 directory.
 
+---
 
 ## Troubleshooting
 
@@ -238,6 +241,8 @@ Solutions:
                 :lang=en_US.UTF-8:
         ```
 
+---
+
 ## Contribute ###
 
 * Writing questions in yaml format
--
libgit2 0.21.2