2 files changed, 20 insertions, 6 deletions

diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md
index 39edf9e19..3de1b99a5 100644
--- a/docs/dev/architecture.md
+++ b/docs/dev/architecture.md
@@ -146,6 +146,8 @@ Reading the docs of the `base_db::input` module should be useful: everything els
 
 **Architecture Invariant:** particularities of the build system are *not* the part of the ground state.
 In particular, `base_db` knows nothing about cargo.
+For example, `cfg` flags are a part of `base_db`, but `feature`s are not.
+A `foo` feature is a Cargo-level concept, which is lowered by Cargo to `--cfg feature=foo` argument on the command line.
 The `CrateGraph` structure is used to represent the dependencies between the crates abstractly.
 
 **Architecture Invariant:** `base_db` doesn't know about file system and file paths.
@@ -447,3 +449,9 @@ This is cheap enough to enable in production.
 
 Similarly, we save live object counting (`RA_COUNT=1`).
 It is not cheap enough to enable in prod, and this is a bug which should be fixed.
+
+### Configurability
+
+rust-analyzer strives to be as configurable as possible while offering reasonable defaults where no configuration exists yet.
+There will always be features that some people find more annoying than helpful, so giving the users the ability to tweak or disable these is a big part of offering a good user experience.
+Mind the code--architecture gap: at the moment, we are using fewer feature flags than we really should.
diff --git a/docs/dev/lsp-extensions.md b/docs/dev/lsp-extensions.md
index fbe2ce1c9..11a3dd04e 100644
--- a/docs/dev/lsp-extensions.md
+++ b/docs/dev/lsp-extensions.md
@@ -25,15 +25,21 @@ rust-analyzer supports clangd's extension for opting into UTF-8 as the coordinat
 
 https://clangd.llvm.org/extensions.html#utf-8-offsets
 
-## `initializationOptions`
+## Configuration in `initializationOptions`
+
+**Issue:** https://github.com/microsoft/language-server-protocol/issues/567
+
+The `initializationOptions` filed of the `InitializeParams` of the initialization request should contain `"rust-analyzer"` section of the configuration.
+
+`rust-analyzer` normally sends a `"workspace/configuration"` request with `{ "items": ["rust-analyzer"] }` payload.
+However, the server can't do this during initialization.
+At the same time some essential configuration parameters are needed early on, before servicing requests.
+For this reason, we ask that `initializationOptions` contains the configuration, as if the server did make a `"workspace/configuration"` request.
 
-For `initializationOptions`, `rust-analyzer` expects `"rust-analyzer"` section of the configuration.
-That is, `rust-analyzer` usually sends `"workspace/configuration"` request with `{ "items": ["rust-analyzer"] }` payload.
-`initializationOptions` should contain the same data that would be in the first item of the result.
 If a language client does not know about `rust-analyzer`'s configuration options it can get sensible defaults by doing any of the following:
  * Not sending `initializationOptions`
- * Send `"initializationOptions": null`
- * Send `"initializationOptions": {}`
+ * Sending `"initializationOptions": null`
+ * Sending `"initializationOptions": {}`
 
 ## Snippet `TextEdit`