improve documentation

[aspiers]

In #39 @waldyrious made a bunch of excellent suggestions about how to improve the documentation. This issue is for tracking the associated work.

[waldyrious]

Glad you liked the suggestions :) I think it would help, first of all, to know your thoughts about the first two points in this comment, and about this comment as well.

[aspiers]

I agree 100% with everything you wrote, including those three points :-) I don't think I have any additional thoughts to add to them off the top of my head.

[waldyrious]

Cool, thanks. I'm a bit swamped at the moment so I don't know when I'll get the chance to tackle this, but I think there's now enough concrete actions that someone else can jump in if there's interest :)