Doc cleanup #2

Hi, this is my second iteration. There are some general grammar fixes, and a fix for an error I introduced by deleting a '----'.

I'm still not very familiar with asciidoc. What are you using to generate the gh-pages?