Readme doc updates

A variety of updates to the README. Two main goals with these updates:

- Be consistent in formatting
- Be consistent in using RSpec 3 syntax
Good catch. It is now. We don't have any notes about that. Sounds like something to add to the upgrade docs.