Update readme.md

#767

Addressed feedback from @baisong's review.  Agreed with all points and implemented them.