[#523] Improve docs based on Sean's feedback