update to docs based on code review comments