improve documentation

Here we collect everything related to improvements of the documentation