linking docs and adding caveats