Improve the documentation

[green-coder]

The README.md file must explain how to use the library.

• Explain more what this library provides, in which ways it can be used.
• Use Clojure snippets inside the markdown doc.
• Choose better examples, replace the talk-like-a-pirate prompt with something closer to realworld usage.