giving the docs a bit more love

[RichMorin]

I'd like to give the Spec docs a bit more love, but I'm not really sure about the best way to approach this. I took a stab at README.md (see master...RichMorin:spec:patch-2), but I may well have gotten assorted things wrong. Also, I don't know if you are still interested in this project. So, let me know...

Aside from the README tweaks, I'd like to try adding some comments and documentation to the code files. Aside from clarifying the intent of the code, this could generate API docs, etc. However, this would also need your feedback and guidance. Finally, it might be really interesting and useful to create a Livebook on Spec. (ducking)