modified docs with sean's comments