Improvements to the user guide, numerous docs fixes

This is a WIP of the user guide. As I've been going I've been fixing all sorts of docs issues, so I propose to get these in now so that others don't redo the same work!

There shouldn't be any code changes - it's all docs.