expanding on the last couple of sections

Tidied up some code samples too.

cc @paulcbetts to give it his blessing
Uh, yeah, not sure what I was thinking there. Will fix.