diff --git a/docs/book/README.md b/docs/book/README.md
index 0a3161f3af..11f7e8f98c 100644
--- a/docs/book/README.md
+++ b/docs/book/README.md
@@ -8,6 +8,7 @@ To run the documentation site locally:
 
 ```shell
 cargo install mdbook
+cargo install mdbook-toc
 cargo xtask codegen
 cd docs/book
 mdbook serve
diff --git a/docs/book/src/faq.md b/docs/book/src/faq.md
index c872033090..8c143ab949 100644
--- a/docs/book/src/faq.md
+++ b/docs/book/src/faq.md
@@ -5,3 +5,12 @@
 rust-analyzer fails to resolve `None`, and thinks you are binding to a variable
 named `None`. That's usually a sign of a corrupted sysroot. Try removing and re-installing
 it: `rustup component remove rust-src` then `rustup component install rust-src`.
+
+### Rust Analyzer and Cargo compete over the build lock
+
+Rust Analyzer invokes Cargo in the background, and it can thus block manually executed
+`cargo` commands from making progress (or vice-versa). In some cases, this can also cause
+unnecessary recompilations caused by cache thrashing. To avoid this, you can configure
+Rust Analyzer to use a [different target directory](./configuration.md#cargo.targetDir).
+This will allow both the IDE and Cargo to make progress independently, at the cost of
+increased disk space usage caused by the duplicated artifact directories.