docs suggestions

Some of these are substance, some are just style and tweaks to make it read, IMO, more smoothly.