diff --git a/docs/images/variable-optimised-out.png b/docs/images/variable-optimised-out.png
new file mode 100644
index 0000000000..2db471e9ee
Binary files /dev/null and b/docs/images/variable-optimised-out.png differ
diff --git a/docs/topics/debug-coroutines-with-idea.md b/docs/topics/debug-coroutines-with-idea.md
index 2c26051da1..b31aa79f51 100644
--- a/docs/topics/debug-coroutines-with-idea.md
+++ b/docs/topics/debug-coroutines-with-idea.md
@@ -100,3 +100,17 @@ The tutorial assumes you have prior knowledge of the [coroutines](coroutines-gui
     * The third coroutine is calculating the value of `b` – it has the **RUNNING** status.
 
 Using IntelliJ IDEA debugger, you can dig deeper into each coroutine to debug your code.
+
+### Optimized-out variables
+
+If you use `suspend` functions, in the debugger, you might see the "was optimized out" text next to a variable's name:
+
+![Variable "a" was optimized out](variable-optimised-out.png)
+
+This text means that the variable's lifetime was decreased, and the variable doesn't exist anymore.
+It is difficult to debug code with optimized variables because you don't see their values.
+You can disable this behavior with the `-Xdebug` compiler option.
+
+> __Never use this flag in production__: `-Xdebug` can [cause memory leaks](https://youtrack.jetbrains.com/issue/KT-48678/Coroutine-debugger-disable-was-optimised-out-compiler-feature#focus=Comments-27-6015585.0-0).
+>
+{type="warning"}
\ No newline at end of file
diff --git a/docs/topics/debug-flow-with-idea.md b/docs/topics/debug-flow-with-idea.md
index 887f67da46..0aa78b1780 100644
--- a/docs/topics/debug-flow-with-idea.md
+++ b/docs/topics/debug-flow-with-idea.md
@@ -102,6 +102,20 @@ Create a Kotlin [flow](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-cor
 
     ![Debug the coroutine](flow-debug-2.png)
 
+### Optimized-out variables
+
+If you use `suspend` functions, in the debugger, you might see the "was optimized out" text next to a variable's name:
+
+![Variable "a" was optimized out](variable-optimised-out.png)
+
+This text means that the variable's lifetime was decreased, and the variable doesn't exist anymore.
+It is difficult to debug code with optimized variables because you don't see their values.
+You can disable this behavior with the `-Xdebug` compiler option.
+
+> __Never use this flag in production__: `-Xdebug` can [cause memory leaks](https://youtrack.jetbrains.com/issue/KT-48678/Coroutine-debugger-disable-was-optimised-out-compiler-feature#focus=Comments-27-6015585.0-0).
+>
+{type="warning"}
+
 ## Add a concurrently running coroutine
 
 1. Open the `Main.kt` file in `src/main/kotlin`.