review and update documentation

make sure that everything is clear and up-to-date