1 files changed, 23 insertions, 3 deletions

diff --git a/docs/user/README.md b/docs/user/README.md
index 036b51d58..f1628d6a4 100644
--- a/docs/user/README.md
+++ b/docs/user/README.md
@@ -1,6 +1,6 @@
 The main interface to rust-analyzer is the
 [LSP](https://microsoft.github.io/language-server-protocol/) implementation. To
-install lsp server, use `cargo install-ra --server`, which is a shorthand for `cargo
+install lsp server, use `cargo xtask install --server`, which is a shorthand for `cargo
 install --package ra_lsp_server`. The binary is named `ra_lsp_server`, you
 should be able to use it with any LSP-compatible editor. We use custom
 extensions to LSP, so special client-side support is required to take full
@@ -33,7 +33,7 @@ following commands:
 ```
 $ git clone https://github.com/rust-analyzer/rust-analyzer.git --depth 1
 $ cd rust-analyzer
-$ cargo install-ra
+$ cargo xtask install
 ```
 
 The automatic installation is expected to *just work* for common cases, if it
@@ -58,9 +58,28 @@ Beyond basic LSP features, there are some extension commands which you can
 invoke via <kbd>Ctrl+Shift+P</kbd> or bind to a shortcut. See [./features.md](./features.md)
 for details.
 
-For updates, pull the latest changes from the master branch, run `cargo install-ra` again, and **restart** VS Code instance.
+For updates, pull the latest changes from the master branch, run `cargo xtask install` again, and **restart** VS Code instance.
 See [microsoft/vscode#72308](https://github.com/microsoft/vscode/issues/72308) for why a full restart is needed.
 
+### VS Code Remote
+
+You can also use `rust-analyzer` with the Visual Studio Code Remote extensions
+(Remote SSH, Remote WSL, Remote Containers). In this case, however, you have to
+manually install the `.vsix` package:
+
+1. Build the extension on the remote host using the instructions above (ignore the
+   error if `code` cannot be found in your PATH: VSCode doesn't need to be installed
+   on the remote host).
+2. In Visual Studio Code open a connection to the remote host.
+3. Open the Extensions View (`View > Extensions`, keyboard shortcut: `Ctrl+Shift+X`).
+4. From the top-right kebab menu (`···`) select `Install from VSIX...`
+5. Inside the `rust-analyzer` directory find the `editors/code` subdirectory and choose
+   the `ra-lsp-0.0.1.vsix` file.
+6. Restart Visual Studio Code and re-establish the connection to the remote host.
+
+In case of errors please make sure that `~/.cargo/bin` is in your `PATH` on the remote
+host.
+
 ### Settings
 
 * `rust-analyzer.highlightingOn`: enables experimental syntax highlighting
@@ -79,6 +98,7 @@ See [microsoft/vscode#72308](https://github.com/microsoft/vscode/issues/72308) f
 * `rust-analyzer.cargo-watch.command`: `cargo-watch` command. (e.g: `clippy` will run as `cargo watch -x clippy` )
 * `rust-analyzer.cargo-watch.arguments`: cargo-watch check arguments.
   (e.g: `--features="shumway,pdf"` will run as `cargo watch -x "check --features="shumway,pdf""` )
+* `rust-analyzer.cargo-watch.ignore`: list of patterns for cargo-watch to ignore (will be passed as `--ignore`)
 * `rust-analyzer.trace.server`: enables internal logging
 * `rust-analyzer.trace.cargo-watch`: enables cargo-watch logging
 * `RUST_SRC_PATH`: environment variable that overwrites the sysroot