documentation update and clarification