diff --git a/packages/docs/src/routes/docs/(qwik)/advanced/eslint/index.mdx b/packages/docs/src/routes/docs/(qwik)/advanced/eslint/index.mdx
index d8cfaad36ef..2dac69a8584 100644
--- a/packages/docs/src/routes/docs/(qwik)/advanced/eslint/index.mdx
+++ b/packages/docs/src/routes/docs/(qwik)/advanced/eslint/index.mdx
@@ -295,6 +295,31 @@ import './styles.css';
+
+
+
+ no-use-visible-task
+ Warning for "useVisibleTask$" usage, because Qwik tries very hard to defer client code execution for as long as possible.
+
+
+
+ ✅
+
+
+ 🔔
+
+
+
Details
@@ -1039,6 +1064,26 @@ import Image from '~/media/image.png';
+
+
+
no-use-visible-task
+
Qwik tries very hard to defer client code execution for as long as possible.
+
This is done to give the end-user the best possible user experience.
+
Running code eagerly blocks the main thread, which prevents the user from interacting until the task is finished.
+"useVisibleTask$" is provided as an escape hatch.
+
When in doubt, instead of "useVisibleTask$()" use:
+
+ - useTask$ -> perform code execution in SSR mode.
+ - useOn() -> listen to events on the root element of the current component.
+ - useOnWindow() -> listen to events on the window object.
+ - useOnDocument() -> listen to events on the document object.
+
+
Sometimes it is the only way to achieve the result.
+
In that case, add:
+
// eslint-disable-next-line qwik/no-use-visible-task
+
to the line before "useVisibleTask$" to acknowledge you understand.
+
+
\ No newline at end of file