some improvements to the docs