further improvements to docs