improvements to docs after discussion w/ Anjani