2 files changed, 25 insertions, 10 deletions

diff --git a/docs/dev/README.md b/docs/dev/README.md
index 24197b332..6bce38e56 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -43,6 +43,10 @@ https://rust-lang.zulipchat.com/#narrow/stream/185405-t-compiler.2Fwg-rls-2.2E0
   while unactionable ones are effectively wont-fix. Each triaged issue should have one of these labels.
 * [fun](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3Afun)
   is for cool, but probably hard stuff.
+* [Design](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%Design)
+  is for moderate/large scale architecture discussion.
+  Also a kind of fun.
+  These issues should generally include a link to a Zulip discussion thread.
 
 # CI
 
@@ -212,7 +216,7 @@ To log all communication between the server and the client, there are two choice
 
 * you can log on the server side, by running something like
   ```
-  env RA_LOG=gen_lsp_server=trace code .
+  env RA_LOG=lsp_server=debug code .
   ```
 
 * you can log on the client side, by enabling `"rust-analyzer.trace.server":
diff --git a/docs/dev/style.md b/docs/dev/style.md
index 7e6cd49e0..6dc6868c2 100644
--- a/docs/dev/style.md
+++ b/docs/dev/style.md
@@ -142,6 +142,17 @@ There are many benefits to this:
 
 Formatting ensures that you can use your editor's "number of selected characters" feature to correlate offsets with test's source code.
 
+## Marked Tests
+
+Use
+[`mark::hit! / mark::check!`](https://github.com/rust-analyzer/rust-analyzer/blob/71fe719dd5247ed8615641d9303d7ca1aa201c2f/crates/test_utils/src/mark.rs)
+when testing specific conditions.
+Do not place several marks into a single test or condition.
+Do not reuse marks between several tests.
+
+**Rationale:** marks provide an easy way to find the canonical test for each bit of code.
+This makes it much easier to understand.
+
 ## Function Preconditions
 
 Express function preconditions in types and force the caller to provide them (rather than checking in callee):
@@ -283,8 +294,9 @@ Prefer `Default` even it has to be implemented manually.
 
 **Rationale:** less typing in the common case, uniformity.
 
-Use `Vec::new` rather than `vec![]`. **Rationale:** uniformity, strength
-reduction.
+Use `Vec::new` rather than `vec![]`.
+
+**Rationale:** uniformity, strength reduction.
 
 ## Functions Over Objects
 
@@ -380,13 +392,12 @@ Compile time **does not** obey this rule -- all code has to be compiled.
 
 ## Appropriate String Types
 
-When interfacing with OS APIs, use `OsString`, even if the original source of
-data is utf-8 encoded. **Rationale:** cleanly delineates the boundary when the
-data goes into the OS-land.
+When interfacing with OS APIs, use `OsString`, even if the original source of data is utf-8 encoded.
+**Rationale:** cleanly delineates the boundary when the data goes into the OS-land.
 
-Use `AbsPathBuf` and `AbsPath` over `std::Path`. **Rationale:** rust-analyzer is
-a long-lived process which handles several projects at the same time. It is
-important not to leak cwd by accident.
+Use `AbsPathBuf` and `AbsPath` over `std::Path`.
+**Rationale:** rust-analyzer is a long-lived process which handles several projects at the same time.
+It is important not to leak cwd by accident.
 
 # Premature Pessimization
 
@@ -469,7 +480,7 @@ pub fn reachable_nodes(node: Node) -> FxHashSet<Node> {
 }
 ```
 
-**Rational:** re-use allocations, accumulator style is more concise for complex cases.
+**Rationale:** re-use allocations, accumulator style is more concise for complex cases.
 
 # Style