more doc clarifications