expanding on the last couple of sections

Tidied up some code samples too.

cc @paulcbetts to give it his blessing