DOC : whole bunch of documentation clean up

To reinforce and extend this idea: I'm afraid there is a trend for people to go straight to the tracker with problems--not just feature requests--that really should be presented first on the list, so that a wider audience has a chance to answer questions.