some improvements to docs