improve doc

some random improvements and additions i stumbled over while updating our project.
looks good to me