update documentation with manu's feedback