Update documentation

This pull request fixes small things : a broken link, a missing warning for the demo, change some paragraphs. See individual commits for more informations.