improve doc

some random improvements and additions i stumbled over while updating our project.
From my experience with the Behat doc, the ReadTheDocs theme does not render sidebars well