A number of improvements to the README document.

Note: moved the namespace change to another pull request.