updated documentation with Amina's first set of comments