fixes and clarifications for documentation