correct numerous errors in documentation
rewording according to discussion on github
Merge pull request #2526 from hamogu/fixdocs

correct numerous errors in documentation