diff --git a/docs/library/machine.rst b/docs/library/machine.rst
index f9dca29875a03b2121b8f7e8e26fd66665fe30bd..ce5edf4938f64bc9c8900f3f0a6774d8db699e02 100644
--- a/docs/library/machine.rst
+++ b/docs/library/machine.rst
@@ -63,13 +63,15 @@ Power related functions
 .. function:: sleep()
 
    Stops the CPU and disables all peripherals except for WLAN. Execution is resumed from
-   the point where the sleep was requested. Wake sources are ``Pin``, ``RTC`` and ``WLAN``.
+   the point where the sleep was requested. For wake up to actually happen, wake sources
+   should be configured first.
 
 .. function:: deepsleep()
 
-   Stops the CPU and all peripherals including WLAN. Execution is resumed from main, just
-   as with a reset. The reset cause can be checked to know that we are coming from
-   ``machine.DEEPSLEEP``. Wake sources are ``Pin`` and ``RTC``.
+   Stops the CPU and all peripherals (including networking interfaces, if any). Execution
+   is resumed from the main script, just as with a reset. The reset cause can be checked
+   to know that we are coming from ``machine.DEEPSLEEP``. For wake up to actually happen,
+   wake sources should be configured first, like ``Pin`` change or ``RTC`` timeout.
 
 .. only:: port_wipy
 
diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst
index 13d9a97f36b7358fd0ff28d608baf2e00781abc2..3c19c75b541926e7ecf866f58b6c2077e16c3b28 100644
--- a/docs/wipy/general.rst
+++ b/docs/wipy/general.rst
@@ -170,9 +170,11 @@ There are currently 2 kinds of errors that you might see:
 2. If the heartbeat LED stays on, then there was a hard fault, you cannot
    recover from this, the only way out is to press the reset switch.
 
-Power consumption in various sleep modes
-----------------------------------------
+Details on sleep modes
+----------------------
 
-* ``machine.idle()`` - ~12mA (in WLAN STA mode)
-* ``machine.sleep()`` - 950uA (in WLAN STA mode)
-* ``machine.deepsleep()`` - ~5uA
+* ``machine.idle()``: Power consumption: ~12mA (in WLAN STA mode). Wake sources:
+  any hardware interrupt, no special configuration required.
+* ``machine.sleep()``: 950uA (in WLAN STA mode). Wake sources are ``Pin``, ``RTC``
+  and ``WLAN``
+* ``machine.deepsleep()``: ~5uA. Wake sources are ``Pin`` and ``RTC``.