adding readme changes

They could still be improved but here are the docs changes in a single pull request.