diff --git a/topics/basics/architectural_overview/threading_model.md b/topics/basics/architectural_overview/threading_model.md
index 1a77f6159..71b2bad8a 100644
--- a/topics/basics/architectural_overview/threading_model.md
+++ b/topics/basics/architectural_overview/threading_model.md
@@ -146,6 +146,29 @@ Read and write actions allow executing a piece of code under a lock, automatical
#### API
{#read-actions-api}
+- [`ReadAction`](%gh-ic%/platform/core-api/src/com/intellij/openapi/application/ReadAction.java) `run()` or `compute()`:
+
+
+
+ ```kotlin
+ val psiFile = ReadAction.compute {
+ // read and return PsiFile
+ }
+ ```
+
+
+
+ ```java
+ PsiFile psiFile = ReadAction.compute(() -> {
+ // read and return PsiFile
+ });
+ ```
+
+
+
+##### Alternative APIs
+{#read-action-alternative-apis collapsible=true default-state=collapsed}
+
- [`Application.runReadAction()`](%gh-ic%/platform/core-api/src/com/intellij/openapi/application/Application.java):
@@ -166,26 +189,7 @@ Read and write actions allow executing a piece of code under a lock, automatical
```
-
-- [`ReadAction`](%gh-ic%/platform/core-api/src/com/intellij/openapi/application/ReadAction.java) `run()` or `compute()`:
-
-
-
- ```kotlin
- val psiFile = ReadAction.compute {
- // read and return PsiFile
- }
- ```
-
-
-
- ```java
- PsiFile psiFile = ReadAction.compute(() -> {
- // read and return PsiFile
- });
- ```
-
-
+ Note that this API is considered low-level and should be avoided.
- Kotlin [`runReadAction()`](%gh-ic%/platform/core-api/src/com/intellij/openapi/application/actions.kt):
```kotlin
@@ -262,26 +266,6 @@ gantt
#### API
{#write-actions-api}
-- [`Application.runWriteAction()`](%gh-ic%/platform/core-api/src/com/intellij/openapi/application/Application.java):
-
-
-
- ```kotlin
- ApplicationManager.application.runWriteAction {
- // write data
- }
- ```
-
-
-
- ```java
- ApplicationManager.getApplication().runWriteAction(() -> {
- // write data
- });
- ```
-
-
-
- [`WriteAction`](%gh-ic%/platform/core-api/src/com/intellij/openapi/application/WriteAction.java) `run()` or `compute()`:
@@ -302,6 +286,30 @@ gantt
+##### Alternative APIs
+{#write-action-alternative-apis collapsible=true default-state=collapsed}
+
+- [`Application.runWriteAction()`](%gh-ic%/platform/core-api/src/com/intellij/openapi/application/Application.java):
+
+
+
+ ```kotlin
+ ApplicationManager.application.runWriteAction {
+ // write data
+ }
+ ```
+
+
+ Note that this API is considered low-level and should be avoided.
+
+ ```java
+ ApplicationManager.getApplication().runWriteAction(() -> {
+ // write data
+ });
+ ```
+
+
+
- Kotlin [`runWriteAction()`](%gh-ic%/platform/core-api/src/com/intellij/openapi/application/actions.kt):
```kotlin
runWriteAction {