Ahead of v1.0 we should re-work the documentation - it has grown organically as features have been added but it's a bit of a mess now.