updated the docs according to the last review