update the docs to make them more readable
fix broken tests