Mau/doc overhaul

rebase of dave/doc overhaul as per GH#255