fixup docs (mostly formatting)

(@stefanpenner / @rjackson)
Merge pull request #3305 from stefanpenner/improve_docs

improve docs (formatting mostly)