[WIP please review] Update docs to match  new markdown style guide.

Now that we have a [markdown style guide](https://github.com/gitlabhq/gitlabhq/blob/master/CONTRIBUTING.md#style-guides) 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.