Eat your own dog food

Just firing up this PR to start a discussion: I think it would be nice to start describing our own API :smile:

If everyone agrees, I can finish this PR by filling the gaps.