improve doc

some random improvements and additions i stumbled over while updating our project.