Documentation update needed

[kamilc]

Some of the docs we have are out of date. We need to update that to match the API we now have.

[rvanlieshout]

Also something about what needs to be done to upgrade to newer versions

[skosch]

@kamilc I've made some changes to the readme file as I'm sure you've seen, but there's probably things missing still. Could you list what needs to be done still? Eventually it'd be nice to have proper hexdocs as well (a man can dream!) ...