improve documentation

fixes #1391

and add improvements/fixes to documentation
Yeap, that's why they were inconsistent. I've moved everything up for now so it's consistent and examples run ok.