doc updates -- caveats