3 files changed, 91 insertions, 36 deletions

diff --git a/docs/dev/README.md b/docs/dev/README.md
index 0c09dddfc..ac7f4fd71 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -41,3 +41,84 @@ We use Travis for CI. Most of the things, including formatting, are checked by
 `cargo test` so, if `cargo test` passes locally, that's a good sign that CI will
 be green as well. We use bors-ng to enforce the [not rocket
 science](https://graydon2.dreamwidth.org/1597.html) rule.
+
+You can run `cargo format-hook` to install git-hook to run rustfmt on commit.
+
+# Code organization
+
+All Rust code lives in the `crates` top-level directory, and is organized as a
+single Cargo workspace. The `editors` top-level directory contains code for
+integrating with editors. Currently, it contains plugins for VS Code (in
+typescript) and Emacs (in elisp). The `docs` top-level directory contains both
+developer and user documentation.
+
+We have some automation infra in Rust in the `crates/tool` package. It contains
+stuff like formatting checking, code generation and powers `cargo install-code`.
+The latter syntax is achieved with the help of cargo aliases (see `.cargo`
+directory).
+
+# Launching rust-analyzer
+
+Debugging language server can be tricky: LSP is rather chatty, so driving it
+from the command line is not really feasible, driving it via VS Code requires
+interacting with two processes.
+
+For this reason, the best way to see how rust-analyzer works is to find a
+relevant test and execute it (VS Code includes an action for running a single
+test).
+
+However, launching a VS Code instance with locally build language server is
+possible. There's even a VS Code task for this, so just <kbd>F5</kbd> should
+work (thanks, [@andrew-w-ross](https://github.com/andrew-w-ross)!).
+
+I often just install development version with `cargo jinstall-lsp` and
+restart the host VS Code.
+
+See [./debugging.md](./debugging.md) for how to attach to rust-analyzer with
+debugger, and don't forget that rust-analyzer has useful `pd` snippet and `dbg`
+postfix completion for printf debugging :-)
+
+# Working With VS Code Extension
+
+To work on the VS Code extension, launch code inside `editors/code` and use `F5`
+to launch/debug. To automatically apply formatter and linter suggestions, use
+`npm run fix`.
+
+# Logging
+
+Logging is done by both rust-analyzer and VS Code, so it might be tricky to
+figure out where logs go.
+
+Inside rust-analyzer, we use the standard `log` crate for logging, and
+`flexi_logger` for logging frotend. By default, log goes to stderr (the same as
+with `env_logger`), but the stderr itself is processed by VS Code. To mirror
+logs to a `./log` directory, set `RA_INTERNAL_MODE=1` environmental variable.
+
+To see stderr in the running VS Code instance, go to the "Output" tab of the
+panel and select `rust-analyzer`. This shows `eprintln!` as well. Note that
+`stdout` is used for the actual protocol, so `println!` will break things.
+
+To log all communication between the server and the client, there are two choices:
+
+* you can log on the server side, by running something like
+  ```
+  env RUST_LOG=gen_lsp_server=trace code .
+  ```
+
+* you can log on the client side, by enabling `"rust-analyzer.trace.server":
+  "verbose"` workspace setting. These logs are shown in a separate tab in the
+  output and could be used with LSP inspector. Kudos to
+  [@DJMcNab](https://github.com/DJMcNab) for setting this awesome infra up!
+
+
+There's also two VS Code commands which might be of interest:
+
+* `Rust Analyzer: Status` shows some memory-usage statistics. To take full
+  advantage of it, you need to compile rust-analyzer with jemalloc support:
+  ```
+  $ cargo install --path crates/ra_lsp_server --force --features jemalloc
+  ```
+
+  There's an alias for this: `cargo jinstall-lsp`.
+
+* `Rust Analyzer: Syntax Tree` shows syntax tree of the current file/selection.
diff --git a/docs/dev/arhictecture.md b/docs/dev/architecture.md
index 57f76ebae..3cd63bf73 100644
--- a/docs/dev/arhictecture.md
+++ b/docs/dev/architecture.md
@@ -7,8 +7,10 @@ in the right place!
 See also the [guide](./guide.md), which walks through a particular snapshot of
 rust-analyzer code base.
 
-For syntax-trees specifically, there's a [video walk
-through](https://youtu.be/DGAuLWdCCAI) as well.
+Yet another resource is this playlist with videos about various parts of the
+analyzer:
+
+https://www.youtube.com/playlist?list=PL85XCvVPmGQho7MZkdW-wtPtuJcFpzycE
 
 ## The Big Picture
 
@@ -61,7 +63,7 @@ processes. These are outlined below:
 
 ## Code Walk-Through
 
-### `crates/ra_syntax`
+### `crates/ra_syntax`, `crates/ra_parser`
 
 Rust syntax tree structure and parser. See
 [RFC](https://github.com/rust-lang/rfcs/pull/2256) for some design notes.
@@ -145,12 +147,14 @@ throughout its modules.
 
 An LSP implementation which wraps `ra_ide_api` into a langauge server protocol.
 
-### `crates/ra_vfs`
+### `ra_vfs`
 
 Although `hir` and `ra_ide_api` don't do any IO, we need to be able to read
 files from disk at the end of the day. This is what `ra_vfs` does. It also
 manages overlays: "dirty" files in the editor, whose "true" contents is
-different from data on disk.
+different from data on disk. This is more or less the single really
+platform-dependent component, so it lives in a separate repository and has an
+extensive cross-platform CI testing.
 
 ### `crates/gen_lsp_server`
 
@@ -164,37 +168,7 @@ Run with `RUST_LOG=sync_lsp_server=debug` to see all the messages.
 
 A CLI interface to rust-analyzer.
 
-### `crate/tools`
-
-Custom Cargo tasks used to develop rust-analyzer:
-
-- `cargo gen-syntax` -- generate `ast` and `syntax_kinds`
-- `cargo gen-tests` -- collect inline tests from grammar
-- `cargo install-code` -- build and install VS Code extension and server
-
-### `editors/code`
-
-VS Code plugin
-
-
-## Common workflows
-
-To try out VS Code extensions, run `cargo install-code`.  This installs both the
-`ra_lsp_server` binary and the VS Code extension. To install only the binary, use
-`cargo install-lsp` (shorthand for `cargo install --path crates/ra_lsp_server --force`)
-
-To see logs from the language server, set `RUST_LOG=info` env variable. To see
-all communication between the server and the client, use
-`RUST_LOG=gen_lsp_server=debug` (this will print quite a bit of stuff).
 
-There's `rust-analyzer: status` command which prints common high-level debug
-info. In particular, it prints info about memory usage of various data
-structures, and, if compiled with jemalloc support (`cargo jinstall-lsp` or 
-`cargo install --path crates/ra_lsp_server --force --features jemalloc`), includes
- statistic about the heap.
+## Testing Infrastructure
 
-To run tests, just `cargo test`.
 
-To work on the VS Code extension, launch code inside `editors/code` and use `F5` to
-launch/debug. To automatically apply formatter and linter suggestions, use `npm
-run fix`.
diff --git a/docs/dev/DEBUGGING.md b/docs/dev/debugging.md
index f868e6998..f868e6998 100644
--- a/docs/dev/DEBUGGING.md
+++ b/docs/dev/debugging.md