update doc based on pwendell's comments