diff --git a/new-docs/puppeteer.frame.md b/new-docs/puppeteer.frame.md
index 314181e462d3e..49903e86df2da 100644
--- a/new-docs/puppeteer.frame.md
+++ b/new-docs/puppeteer.frame.md
@@ -92,5 +92,6 @@ console.log(text);
| [waitForFunction(pageFunction, options, args)](./puppeteer.frame.waitforfunction.md) | | |
| [waitForNavigation(options)](./puppeteer.frame.waitfornavigation.md) | | |
| [waitForSelector(selector, options)](./puppeteer.frame.waitforselector.md) | | |
+| [waitForTimeout(milliseconds)](./puppeteer.frame.waitfortimeout.md) | | Causes your script to wait for the given number of milliseconds. |
| [waitForXPath(xpath, options)](./puppeteer.frame.waitforxpath.md) | | |
diff --git a/new-docs/puppeteer.frame.waitfor.md b/new-docs/puppeteer.frame.waitfor.md
index a38d2341e5536..6e07960173929 100644
--- a/new-docs/puppeteer.frame.waitfor.md
+++ b/new-docs/puppeteer.frame.waitfor.md
@@ -4,6 +4,11 @@
## Frame.waitFor() method
+> Warning: This API is now obsolete.
+>
+> Don't use this method directly. Instead use the more explicit methods available: [Frame.waitForSelector()](./puppeteer.frame.waitforselector.md), [Frame.waitForXPath()](./puppeteer.frame.waitforxpath.md), [Frame.waitForFunction()](./puppeteer.frame.waitforfunction.md) or [Frame.waitForTimeout()](./puppeteer.frame.waitfortimeout.md).
+>
+
Signature:
```typescript
diff --git a/new-docs/puppeteer.frame.waitfortimeout.md b/new-docs/puppeteer.frame.waitfortimeout.md
new file mode 100644
index 0000000000000..71dd10759b450
--- /dev/null
+++ b/new-docs/puppeteer.frame.waitfortimeout.md
@@ -0,0 +1,37 @@
+
+
+[Home](./index.md) > [puppeteer](./puppeteer.md) > [Frame](./puppeteer.frame.md) > [waitForTimeout](./puppeteer.frame.waitfortimeout.md)
+
+## Frame.waitForTimeout() method
+
+Causes your script to wait for the given number of milliseconds.
+
+Signature:
+
+```typescript
+waitForTimeout(milliseconds: number): Promise;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| milliseconds | number | the number of milliseconds to wait. |
+
+Returns:
+
+Promise<void>
+
+## Remarks
+
+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
+
+Wait for 1 second:
+
+```
+await frame.waitForTimeout(1000);
+
+```
+
diff --git a/new-docs/puppeteer.page.md b/new-docs/puppeteer.page.md
index 6b23980db7441..2530230a600ed 100644
--- a/new-docs/puppeteer.page.md
+++ b/new-docs/puppeteer.page.md
@@ -138,6 +138,7 @@ page.off('request', logRequest);
| [waitForRequest(urlOrPredicate, options)](./puppeteer.page.waitforrequest.md) | | |
| [waitForResponse(urlOrPredicate, options)](./puppeteer.page.waitforresponse.md) | | |
| [waitForSelector(selector, options)](./puppeteer.page.waitforselector.md) | | |
+| [waitForTimeout(milliseconds)](./puppeteer.page.waitfortimeout.md) | | Causes your script to wait for the given number of milliseconds. |
| [waitForXPath(xpath, options)](./puppeteer.page.waitforxpath.md) | | |
| [workers()](./puppeteer.page.workers.md) | | |
diff --git a/new-docs/puppeteer.page.waitfor.md b/new-docs/puppeteer.page.waitfor.md
index e808df9af69a8..8cd12e5a9e301 100644
--- a/new-docs/puppeteer.page.waitfor.md
+++ b/new-docs/puppeteer.page.waitfor.md
@@ -4,6 +4,11 @@
## Page.waitFor() method
+> Warning: This API is now obsolete.
+>
+> Don't use this method directly. Instead use the more explicit methods available: [Page.waitForSelector()](./puppeteer.page.waitforselector.md), [Page.waitForXPath()](./puppeteer.page.waitforxpath.md), [Page.waitForFunction()](./puppeteer.page.waitforfunction.md) or [Page.waitForTimeout()](./puppeteer.page.waitfortimeout.md).
+>
+
Signature:
```typescript
@@ -19,11 +24,19 @@ waitFor(selectorOrFunctionOrTimeout: string | number | Function, options?: {
| Parameter | Type | Description |
| --- | --- | --- |
-| selectorOrFunctionOrTimeout | string \| number \| Function | |
-| options | { visible?: boolean; hidden?: boolean; timeout?: number; polling?: string \| number; } | |
-| args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)\[\] | |
+| selectorOrFunctionOrTimeout | string \| number \| Function | a selector, predicate or timeout to wait for. |
+| options | { visible?: boolean; hidden?: boolean; timeout?: number; polling?: string \| number; } | optional waiting parameters. |
+| args | [SerializableOrJSHandle](./puppeteer.serializableorjshandle.md)\[\] | arguments to pass to pageFunction. |
Returns:
Promise<[JSHandle](./puppeteer.jshandle.md)>
+## Remarks
+
+This method behaves differently depending on the first parameter. If it's a `string`, it will be treated as a `selector` or `xpath` (if the string starts with `//`). This method then is a shortcut for [Page.waitForSelector()](./puppeteer.page.waitforselector.md) or [Page.waitForXPath()](./puppeteer.page.waitforxpath.md).
+
+If the first argument is a function this method is a shortcut for [Page.waitForFunction()](./puppeteer.page.waitforfunction.md).
+
+If the first argument is a `number`, it's treated as a timeout in milliseconds and the method returns a promise which resolves after the timeout.
+
diff --git a/new-docs/puppeteer.page.waitfortimeout.md b/new-docs/puppeteer.page.waitfortimeout.md
new file mode 100644
index 0000000000000..1b74ebb6289b0
--- /dev/null
+++ b/new-docs/puppeteer.page.waitfortimeout.md
@@ -0,0 +1,37 @@
+
+
+[Home](./index.md) > [puppeteer](./puppeteer.md) > [Page](./puppeteer.page.md) > [waitForTimeout](./puppeteer.page.waitfortimeout.md)
+
+## Page.waitForTimeout() method
+
+Causes your script to wait for the given number of milliseconds.
+
+Signature:
+
+```typescript
+waitForTimeout(milliseconds: number): Promise;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| milliseconds | number | the number of milliseconds to wait. |
+
+Returns:
+
+Promise<void>
+
+## 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.
+
+## Example
+
+Wait for 1 second:
+
+```
+await page.waitForTimeout(1000);
+
+```
+
diff --git a/src/common/FrameManager.ts b/src/common/FrameManager.ts
index 46e0f044315e7..640b47a1743e0 100644
--- a/src/common/FrameManager.ts
+++ b/src/common/FrameManager.ts
@@ -1036,7 +1036,7 @@ export class Frame {
* @param options - optional waiting parameters.
* @param args - arguments to pass to `pageFunction`.
*
- * @deprecated don't use this method directly. Instead use the more explicit
+ * @deprecated Don't use this method directly. Instead use the more explicit
* methods available: {@link Frame.waitForSelector},
* {@link Frame.waitForXPath}, {@link Frame.waitForFunction} or
* {@link Frame.waitForTimeout}.
diff --git a/src/common/Page.ts b/src/common/Page.ts
index 65c63bce09592..211b1bcba8475 100644
--- a/src/common/Page.ts
+++ b/src/common/Page.ts
@@ -1877,7 +1877,7 @@ export class Page extends EventEmitter {
* @param options - optional waiting parameters.
* @param args - arguments to pass to `pageFunction`.
*
- * @deprecated don't use this method directly. Instead use the more explicit
+ * @deprecated Don't use this method directly. Instead use the more explicit
* methods available: {@link Page.waitForSelector},
* {@link Page.waitForXPath}, {@link Page.waitForFunction} or
* {@link Page.waitForTimeout}.