DOC : whole bunch of documentation clean up

You should *consider*....