Misc docs suggestions

I understand what you mean but don't know how to address it so I have pushed another update reverting the change. If you don't want history garbage I can rebase the changes to drop the commits completely.