DOC : whole bunch of documentation clean up

I started at the outside and worked my way in.  Even if this is not perfect, we *need* to have this marked up figure someplace in the docs.