improve doc

some random improvements and additions i stumbled over while updating our project.
we have to check if this renders well.