Update docs

@keflavich @ChrisBeaumont - I've tried to tidy up the documentation a bit. What do you think?