Improving documentation

Normally I would submit a squashed commit, but I want to keep each item clear. @jodosha if you prefer I can split these into individual pull requests.