Update docs to match new markdown style guide.

Created by: cirosantilli

Now that we have a markdown style guide I've started updating the docs to match that guide.

I have updated part of the docs. Please check that this is OK, and if yes I will finish updating the rest of the guide.

If you don't agree with the style in guide, please open an issue / pull request directly at: https://github.com/cirosantilli/markdown-styleguide for us to discuss and link to it from here.

The main changes include:

• don't wrap long lines: http://www.cirosantilli.com/markdown-styleguide/#line-wrapping

• convert every list marker to -. Currently both + and * are used.

• convert lists with paragraphs to triple spaces after marker:

  -   a
  
      b

  Greater portability: http://www.cirosantilli.com/markdown-styleguide/#spaces-after-marker

• remove multiple consecutive empty lines

• add top-level headers everywhere