docs clarifications