ENH: doc updates no.1

Addresses parts of #862