Review first 8 parts of the doc

This commit mostly fixes typos but also improves slightly specific
areas, adding links when it make sense.
Merge pull request #508 from snicoll/docs

* docs:
  Review first 8 parts of the doc