Batch of improvements around error handling, useability, and documentation

[sam-github]

Probably all I have time to do in the short-term, so also includes a TODO list, maybe someone will pick up the challenge.

[easternbloc]

Cheers Sam