Update README.md
documentation improvements

resolves #124
Merge branch 'master' into gh-pages