doc clarifications & fixes