DOC : whole bunch of documentation clean up

> In fact, at the matplotlib BoF, I plan to play devil's advocate and argue for keeping pylab around.

Sounds like fun - I'll be curious to hear your arguments :wink: