diff --git a/docs/api/puppeteer.frame.md b/docs/api/puppeteer.frame.md
index a0c6ad27f1c..54a9e0ff4c3 100644
--- a/docs/api/puppeteer.frame.md
+++ b/docs/api/puppeteer.frame.md
@@ -93,5 +93,5 @@ console.log(text);
 | [waitForFunction(pageFunction, options, args)](./puppeteer.frame.waitforfunction.md) |           |                                                                                                                                                                                                                                                                            |
 | [waitForNavigation(options)](./puppeteer.frame.waitfornavigation.md)                 |           | <p>Waits for the frame to navigate. It is useful for when you run code which will indirectly cause the frame to navigate.</p><p>Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the URL is considered a navigation.</p> |
 | [waitForSelector(selector, options)](./puppeteer.frame.waitforselector.md)           |           | <p>Waits for an element matching the given selector to appear in the frame.</p><p>This method works across navigations.</p>                                                                                                                                                |
-| [waitForTimeout(milliseconds)](./puppeteer.frame.waitfortimeout.md)                  |           | Causes your script to wait for the given number of milliseconds.                                                                                                                                                                                                           |
+| [waitForTimeout(milliseconds)](./puppeteer.frame.waitfortimeout.md)                  |           |                                                                                                                                                                                                                                                                            |
 | [waitForXPath(xpath, options)](./puppeteer.frame.waitforxpath.md)                    |           |                                                                                                                                                                                                                                                                            |
diff --git a/docs/api/puppeteer.frame.waitfortimeout.md b/docs/api/puppeteer.frame.waitfortimeout.md
index d8e670e9d5b..586603185c4 100644
--- a/docs/api/puppeteer.frame.waitfortimeout.md
+++ b/docs/api/puppeteer.frame.waitfortimeout.md
@@ -6,9 +6,9 @@ sidebar_label: Frame.waitForTimeout
 
 > Warning: This API is now obsolete.
 >
-> DO NOT USE.
-
-Causes your script to wait for the given number of milliseconds.
+> Use `new Promise(r => setTimeout(r, milliseconds));`.
+>
+> Causes your script to wait for the given number of milliseconds.
 
 **Signature:**
 
@@ -36,6 +36,6 @@ It's generally recommended to not wait for a number of seconds, but instead use
 
 Wait for 1 second:
 
-```
+```ts
 await frame.waitForTimeout(1000);
 ```
diff --git a/docs/api/puppeteer.page.md b/docs/api/puppeteer.page.md
index ef5548f20a5..21f2efa9e01 100644
--- a/docs/api/puppeteer.page.md
+++ b/docs/api/puppeteer.page.md
@@ -174,7 +174,7 @@ const puppeteer = require('puppeteer');
 ```
 
 |
-| [waitForTimeout(milliseconds)](./puppeteer.page.waitfortimeout.md) | | Causes your script to wait for the given number of milliseconds. |
+| [waitForTimeout(milliseconds)](./puppeteer.page.waitfortimeout.md) | | |
 | [waitForXPath(xpath, options)](./puppeteer.page.waitforxpath.md) | | <p>Wait for the <code>xpath</code> to appear in page. If at the moment of calling the method the <code>xpath</code> already exists, the method will return immediately. If the <code>xpath</code> doesn't appear after the <code>timeout</code> milliseconds of waiting, the function will throw.</p><p>This method works across navigation</p>
 
 ```ts
diff --git a/docs/api/puppeteer.page.waitfortimeout.md b/docs/api/puppeteer.page.waitfortimeout.md
index f42a5aa049b..6722cc7ac25 100644
--- a/docs/api/puppeteer.page.waitfortimeout.md
+++ b/docs/api/puppeteer.page.waitfortimeout.md
@@ -4,7 +4,11 @@ sidebar_label: Page.waitForTimeout
 
 # Page.waitForTimeout() method
 
-Causes your script to wait for the given number of milliseconds.
+> Warning: This API is now obsolete.
+>
+> Use `new Promise(r => setTimeout(r, milliseconds));`.
+>
+> Causes your script to wait for the given number of milliseconds.
 
 **Signature:**
 
@@ -26,7 +30,7 @@ Promise&lt;void&gt;
 
 ## Remarks
 
-It's generally recommended to not wait for a number of seconds, but instead use [Page.waitForSelector()](./puppeteer.page.waitforselector.md), [Page.waitForXPath()](./puppeteer.page.waitforxpath.md) or [Page.waitForFunction()](./puppeteer.page.waitforfunction.md) to wait for exactly the conditions you want.
+It's generally recommended to not wait for a number of seconds, but instead use [Frame.waitForSelector()](./puppeteer.frame.waitforselector.md), [Frame.waitForXPath()](./puppeteer.frame.waitforxpath.md) or [Frame.waitForFunction()](./puppeteer.frame.waitforfunction.md) to wait for exactly the conditions you want.
 
 ## Example
 
diff --git a/src/common/FrameManager.ts b/src/common/FrameManager.ts
index 06d82641590..99923860269 100644
--- a/src/common/FrameManager.ts
+++ b/src/common/FrameManager.ts
@@ -1402,6 +1402,8 @@ export class Frame {
   }
 
   /**
+   * @deprecated Use `new Promise(r => setTimeout(r, milliseconds));`.
+   *
    * Causes your script to wait for the given number of milliseconds.
    *
    * @remarks
@@ -1413,13 +1415,11 @@ export class Frame {
    *
    * Wait for 1 second:
    *
-   * ```
+   * ```ts
    * await frame.waitForTimeout(1000);
    * ```
    *
    * @param milliseconds - the number of milliseconds to wait.
-   *
-   * @deprecated DO NOT USE.
    */
   waitForTimeout(milliseconds: number): Promise<void> {
     return new Promise(resolve => {
diff --git a/src/common/Page.ts b/src/common/Page.ts
index 248c9889562..ffd65287ae0 100644
--- a/src/common/Page.ts
+++ b/src/common/Page.ts
@@ -3318,13 +3318,14 @@ export class Page extends EventEmitter {
   }
 
   /**
+   * @deprecated Use `new Promise(r => setTimeout(r, milliseconds));`.
+   *
    * Causes your script to wait for the given number of milliseconds.
    *
    * @remarks
-   *
    * It's generally recommended to not wait for a number of seconds, but instead
-   * use {@link Page.waitForSelector}, {@link Page.waitForXPath} or
-   * {@link Page.waitForFunction} to wait for exactly the conditions you want.
+   * use {@link Frame.waitForSelector}, {@link Frame.waitForXPath} or
+   * {@link Frame.waitForFunction} to wait for exactly the conditions you want.
    *
    * @example
    *