improvements and fixes to docs