DOC : whole bunch of documentation clean up

I'd like to be a little more positive with this whole paragraph. Maybe we can talk during the scipy sprint.