DOC : whole bunch of documentation clean up

Comment that this is an open source project, and that there is no way that we can guarantee that it will get done...