more doc updates for clarity