diff --git a/docs/src/api/class-clock.md b/docs/src/api/class-clock.md
index f2ee2433b4..38ca329769 100644
--- a/docs/src/api/class-clock.md
+++ b/docs/src/api/class-clock.md
@@ -193,6 +193,8 @@ Resumes timers. Once this method is called, time resumes flowing, timers are fir
 Makes `Date.now` and `new Date()` return fixed fake time at all times,
 keeps all the timers running.
 
+Use this method for simple scenarios where you only need to test with a predefined time. For more advanced scenarios, use [`method: Clock.install`] instead. Read docs on [clock emulation](../clock.md) to learn more.
+
 **Usage**
 
 ```js
@@ -249,7 +251,7 @@ Time to be set.
 ## async method: Clock.setSystemTime
 * since: v1.45
 
-Sets current system time but does not trigger any timers.
+Sets system time, but does not trigger any timers. Use this to test how the web page reacts to a time shift, for example switching from summer to winter time, or changing time zones.
 
 **Usage**
 
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index 0ecdf93904..fe182dac4e 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -18544,6 +18544,10 @@ export interface Clock {
   /**
    * Makes `Date.now` and `new Date()` return fixed fake time at all times, keeps all the timers running.
    *
+   * Use this method for simple scenarios where you only need to test with a predefined time. For more advanced
+   * scenarios, use [clock.install([options])](https://playwright.dev/docs/api/class-clock#clock-install) instead. Read
+   * docs on [clock emulation](https://playwright.dev/docs/clock) to learn more.
+   *
    * **Usage**
    *
    * ```js
@@ -18557,7 +18561,8 @@ export interface Clock {
   setFixedTime(time: number|string|Date): Promise<void>;
 
   /**
-   * Sets current system time but does not trigger any timers.
+   * Sets system time, but does not trigger any timers. Use this to test how the web page reacts to a time shift, for
+   * example switching from summer to winter time, or changing time zones.
    *
    * **Usage**
    *