some clarifications in doc [ci skip]