diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
index a4279dffde..d8d4fad373 100644
--- a/docs/src/api/class-page.md
+++ b/docs/src/api/class-page.md
@@ -2046,7 +2046,7 @@ Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
 - returns: <[null]|[ElementHandle]>
 
 The method finds an element matching the specified selector within the page. If no elements match the selector, the
-return value resolves to `null`.
+return value resolves to `null`. To wait for an element on the page, use [`method: Page.waitForSelector`].
 
 Shortcut for main frame's [`method: Frame.querySelector`].
 
diff --git a/types/types.d.ts b/types/types.d.ts
index d021a7975c..e69fc50964 100644
--- a/types/types.d.ts
+++ b/types/types.d.ts
@@ -167,7 +167,8 @@ export interface Page {
 
   /**
    * The method finds an element matching the specified selector within the page. If no elements match the selector, the
-   * return value resolves to `null`.
+   * return value resolves to `null`. To wait for an element on the page, use
+   * [page.waitForSelector(selector[, options])](https://playwright.dev/docs/api/class-page#pagewaitforselectorselector-options).
    *
    * Shortcut for main frame's [frame.$(selector)](https://playwright.dev/docs/api/class-frame#frameselector).
    * @param selector A selector to query for. See [working with selectors](https://playwright.dev/docs/selectors) for more details.