improve doc according to review (thanks @kobliha)