diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst
old mode 100644
new mode 100755
index 6c07c584d3..a49f8fd39e
--- a/docs/esp32/quickref.rst
+++ b/docs/esp32/quickref.rst
@@ -578,7 +578,7 @@ See :ref:`machine.WDT <machine.WDT>`. ::
     from machine import WDT
 
     # enable the WDT with a timeout of 5s (1s is the minimum)
-    wdt = WDT(timeout=5000)
+    wdt = WDT(timeout=5000)  # timeout in milliseconds
     wdt.feed()
 
 .. _Deep_sleep_mode:
diff --git a/docs/esp32/tutorial/index.rst b/docs/esp32/tutorial/index.rst
old mode 100644
new mode 100755
index c6242d731f..47820ee60c
--- a/docs/esp32/tutorial/index.rst
+++ b/docs/esp32/tutorial/index.rst
@@ -20,4 +20,5 @@ to `<https://www.python.org>`__.
 
    intro.rst
    pwm.rst
+   wdt.rst
    peripheral_access.rst
diff --git a/docs/esp32/tutorial/wdt.rst b/docs/esp32/tutorial/wdt.rst
new file mode 100755
index 0000000000..11fc2b8021
--- /dev/null
+++ b/docs/esp32/tutorial/wdt.rst
@@ -0,0 +1,43 @@
+
+.. _esp32_wdt:
+
+WDT
+===
+
+When the WDT timeout is short, a problem occurs when updating the software:
+you don't have enough time to copy the updates to the device.
+ESP32 allows reinitialise the watchdog with a longer timeout - like an hour.
+
+More comprehansive example usage::
+
+    # Save as 'main.py' and it will run automatically after 'boot.py'
+
+    import sys
+    from time import sleep
+    from machine import WDT, reset
+
+    try:
+        print('Press Ctrl-C to break the program.')
+        sleep(5)
+        print('Enable the WDT with a timeout of 5s.')
+        wdt = WDT(timeout=5000)
+
+        seconds = 1
+        while True:  # infinite work loop
+            print('Do something useful in less than 5 seconds.')
+            print(f'Sleep {seconds} seconds.')
+            if seconds >= 5:
+                print(f'WDT will reboot the board.')
+            sleep(seconds)
+            seconds += 1
+            wdt.feed()
+
+            # 1/0  # uncomment this line to raise an runtime exception, then WDT reboot
+
+            # sys.exit()  # uncomment this line for planned program exit
+
+    except SystemExit:
+        wdt = WDT(timeout=1000 * 60 * 60)  # 1 hour before WDT reboot
+        print('Now you have 1 hour to update program on the board.')
+        print('When ready, type reset() on the REPL/WebREPL command line to reboot.')
+
diff --git a/docs/library/machine.WDT.rst b/docs/library/machine.WDT.rst
old mode 100644
new mode 100755
index cf77df9632..78a49113b2
--- a/docs/library/machine.WDT.rst
+++ b/docs/library/machine.WDT.rst
@@ -5,15 +5,17 @@ class WDT -- watchdog timer
 ===========================
 
 The WDT is used to restart the system when the application crashes and ends
-up into a non recoverable state. Once started it cannot be stopped or
-reconfigured in any way. After enabling, the application must "feed" the
+up into a non recoverable state. Once started it cannot be stopped
+in any way. After enabling, the application must "feed" the
 watchdog periodically to prevent it from expiring and resetting the system.
 
 Example usage::
 
     from machine import WDT
     wdt = WDT(timeout=2000)  # enable it with a timeout of 2s
-    wdt.feed()
+    while True:
+        # do something useful in less than 2 seconds
+        wdt.feed()
 
 Availability of this class: pyboard, WiPy, esp8266, esp32, rp2040, mimxrt.