incorporate doc review comments

Signed-off-by: Madhav Puri <madhav.puri@gmail.com>