Incorporate user documentation to README

[adehad]

Summary

1. Proposes an outline for the README that incorporates the user documentation.

Style guide to follow

• [ ] Each sentence starts on new line
• [ ] Wrap at 79
• [ ] 2 blank lines before headings
• [ ] backtick fenced code blocks

Apparently GitHub has a .md toc sidebar that may help reviewing:

https://github.com/adehad/pyyaml#readme