readme: add docs

Continued from #2

cc @rlidwka
Now that I read this, both the former and the new wording is weird.