clarify docs with bruce's feedback