Readme improvements

Note: doctests caught some errors in the code examples