DOC : whole bunch of documentation clean up

Generally I agree with the need for this document, but I'm not 100% comfortable with the approach taken. It might be worth getting a novice onboard to help get some coherent structure to the way things are introduced.