diff --git a/README.md b/README.md
index c18f249..7c6d2c0 100644
--- a/README.md
+++ b/README.md
@@ -3,9 +3,11 @@
 
 # Rust for Visual Studio Code (Latest: 0.3.7)
 
-## Why the fork?
+## What is the repository?
 
-RustyCode is no longer maintained and the developer seems to have lost all interest in the extension. Due to no response from the original author, this fork was created which now contains additional features and many bug fixes.
+The extension is continuation of RustyCode (an extension for Visual Studio Code for Rust language).
+
+RustyCode is no longer maintained and the developer seems to have lost all interest in the extension. Due to no response from the original author, this repository was created which now contains additional features and many bug fixes.
 
 ## Extension
 
diff --git a/doc/format.md b/doc/format.md
index 55f8582..5e8de18 100644
--- a/doc/format.md
+++ b/doc/format.md
@@ -2,7 +2,7 @@
 
 The extension supports formatting the document opened in the active text editor on saving.
 
-If the extension is runnning in [RLS Mode](rls_mode.md), formatting is performed via `rustfmt` integrated into RLS.
+If the extension is runnning in [RLS Mode](rls_mode/main.md), formatting is performed via `rustfmt` integrated into RLS.
 
 If the extension is running in [Legacy Mode](legacy_mode/main.md), formatting is performed via separate `rustfmt`.
 
diff --git a/doc/legacy_mode/linting.md b/doc/legacy_mode/linting.md
new file mode 100644
index 0000000..0b2cdc4
--- /dev/null
+++ b/doc/legacy_mode/linting.md
@@ -0,0 +1,29 @@
+# Linting In Legacy Mode
+
+Executing a cargo command makes the extension parse the the command's output and show diagnostics.
+
+Legacy Mode cannot show diagnostics as you type, for that you should use [RLS Mode](../rls_mode/linting.md).
+
+Let's assume we have the following code:
+
+```rust
+fn main() {
+    let x = 5 + "10";
+}
+```
+
+We then execute any cargo command. Let's execute ["Cargo: Build"](../cargo_command_execution.md).
+
+It builds and shows diagnostics:
+
+* In the source code:
+
+[![Linting](../../images/linting/code.jpg)]()
+
+* And In the Problems panel:
+
+[![Linting](../../images/linting/problems_panel_legacy_mode.jpg)]()
+
+We can hover over any diagnostic to see what it is:
+
+[![Linting](../../images/linting/code_hover_legacy_mode.jpg)]()
diff --git a/doc/linting.md b/doc/linting.md
new file mode 100644
index 0000000..b32c163
--- /dev/null
+++ b/doc/linting.md
@@ -0,0 +1,23 @@
+# Linting Page
+
+The extension provides linting as shown in the following screenshot:
+
+[![Linting](../images/linting/code.jpg)]()
+
+It also populates the Problems panel.
+
+For the code:
+
+```rust
+fn foo(i: i32) {}
+
+fn main() {
+    foo(2i64);
+}
+```
+
+The Problems panel would look like:
+
+[![Linting](../images/linting/problems_panel.jpg)]()
+
+Linting behaves differently in [RLS Mode](rls_mode/linting.md) than in [Legacy Mode](legacy_mode/linting.md).
diff --git a/doc/main.md b/doc/main.md
index 614fb4d..5528b6d 100644
--- a/doc/main.md
+++ b/doc/main.md
@@ -9,15 +9,16 @@ The documentation describes features supported by the extension.
 The extension can function in one of two modes:
 
 * [Legacy Mode](legacy_mode/main.md)
-* [Rust Language Server Mode](rls_mode.md)
+* [Rust Language Server Mode](rls_mode/main.md)
 
 Each mode is described in detail on its own page.
 
-Furthermore, the extension allows:
+Furthermore, the extension provides:
 
-* [To execute one of built-in cargo command](cargo_command_execution.md)
-* [To create a playground](playground_creation.md)
-* [To format a document opened in the active text editor](format.md)
+* [Linting (the showing of diagnostics in the active text editor)](linting.md)
+* [Executing one of built-in cargo command](cargo_command_execution.md)
+* [Creating a playground](playground_creation.md)
+* [Formatting a document opened in the active text editor](format.md)
 
 Also it provides snippets and keybindings.
 
diff --git a/doc/rls_mode/linting.md b/doc/rls_mode/linting.md
new file mode 100644
index 0000000..b8e1edf
--- /dev/null
+++ b/doc/rls_mode/linting.md
@@ -0,0 +1,15 @@
+# Linting in Rust Language Server Mode
+
+RLS checks the project and shows diagnostics while you are typing.
+
+You can see diagnostics in the Problems panel.
+
+You can hover over a diagnostic to see what the problem is.
+
+Executing a cargo command doesn't show any diagnostics (unlike [Legacy Mode](../legacy_mode/linting.md)).
+
+It is intentional design decision.
+
+The reason is that there is no pretty way to hide a diagnostic after the diagnostic's cause is fixed.
+
+That (the showing of a problem which has been already fixed) may confuse people, hence the decision.
diff --git a/doc/rls_mode.md b/doc/rls_mode/main.md
similarity index 100%
rename from doc/rls_mode.md
rename to doc/rls_mode/main.md
diff --git a/images/linting/code.jpg b/images/linting/code.jpg
new file mode 100644
index 0000000..f0ac458
Binary files /dev/null and b/images/linting/code.jpg differ
diff --git a/images/linting/code_hover_legacy_mode.jpg b/images/linting/code_hover_legacy_mode.jpg
new file mode 100644
index 0000000..7478fd9
Binary files /dev/null and b/images/linting/code_hover_legacy_mode.jpg differ
diff --git a/images/linting/problems_panel.jpg b/images/linting/problems_panel.jpg
new file mode 100644
index 0000000..216d6e4
Binary files /dev/null and b/images/linting/problems_panel.jpg differ
diff --git a/images/linting/problems_panel_legacy_mode.jpg b/images/linting/problems_panel_legacy_mode.jpg
new file mode 100644
index 0000000..f3c9358
Binary files /dev/null and b/images/linting/problems_panel_legacy_mode.jpg differ