Update project documentation

We need detailed instructions for other people to use this package and
contribute to the project.

This should make it clearer for new devs what is going on in the code
and it should give people directions about where to start looking at the
codebase.
There is also references to Emacs Lisp learning material.