Add troubleshooting FAQ to the book

And one frequently asked question.

3 files changed, 12 insertions, 0 deletions

diff --git a/src/tools/rust-analyzer/docs/book/src/SUMMARY.md b/src/tools/rust-analyzer/docs/book/src/SUMMARY.md
index 1f211a97d78..dffdae94a6e 100644
--- a/src/tools/rust-analyzer/docs/book/src/SUMMARY.md
+++ b/src/tools/rust-analyzer/docs/book/src/SUMMARY.md
@@ -6,6 +6,7 @@
   - [rust-analyzer Binary](rust_analyzer_binary.md)
   - [Other Editors](other_editors.md)
 - [Troubleshooting](troubleshooting.md)
+  - [FAQ](faq.md)
 - [Configuration](configuration.md)
   - [Non-Cargo Based Projects](non_cargo_based_projects.md)
 - [Security](security.md)
diff --git a/src/tools/rust-analyzer/docs/book/src/faq.md b/src/tools/rust-analyzer/docs/book/src/faq.md
new file mode 100644
index 00000000000..c8720330901
--- /dev/null
+++ b/src/tools/rust-analyzer/docs/book/src/faq.md
@@ -0,0 +1,7 @@
+# Troubleshooting FAQ
+
+### I see a warning "Variable `None` should have snake_case name, e.g. `none`"
+
+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`.
diff --git a/src/tools/rust-analyzer/docs/book/src/troubleshooting.md b/src/tools/rust-analyzer/docs/book/src/troubleshooting.md
index 1b2841421a4..3f7caf0db4b 100644
--- a/src/tools/rust-analyzer/docs/book/src/troubleshooting.md
+++ b/src/tools/rust-analyzer/docs/book/src/troubleshooting.md
@@ -1,5 +1,9 @@
 # Troubleshooting
 
+First, search the [troubleshooting FAQ](troubleshooting/faq.html). If
+your problem appears there (and the proposed solution works for you),
+great! Otherwise, read on.
+
 Start with looking at the rust-analyzer version. Try **rust-analyzer:
 Show RA Version** in VS Code (using **Command Palette** feature
 typically activated by Ctrl+Shift+P) or `rust-analyzer --version` in the