Feature/doc fixes

Hi there!

I decided to dive in and start with the docs. If it's OK with you, I'd start with the README and go through it item by item, trying to add more examples that could later be broken off into more comprehensive documentation. 

I've just started, so this pull request is more of a sample that I'd add to until you're happy enough with it to merge.

Let me know if there's something in particular you'd like to see covered/revised.