further clarify docs based on feedback