update README and related files
misc fixes and additions
addressed comments
Merge pull request #181 from mdsol/feature/update_documentation

Merged!