diff --git a/ev3dev/core.py b/ev3dev/core.py
index 5a43bf8..bc53140 100644
--- a/ev3dev/core.py
+++ b/ev3dev/core.py
@@ -843,7 +843,15 @@ def wait_until(self, s, timeout=None):
         Blocks until ``s`` is in ``self.state``.  The condition is checked when
         there is an I/O event related to the ``state`` attribute.  Exits early
         when ``timeout`` (in milliseconds) is reached.
-
+        
+        **Warning:** In ev3dev kernel release cycles 16 and earlier, there is
+        a bug which causes the ``state`` attribute to include ``stalled``
+        immediately after starting the motor even if it is not actually being
+        prevented from rotating. As a workaround, we recommend sleeping your
+        code for around 100ms after starting a motor if you are going to use
+        this method to wait for it to be ``stalled``. A fix for this has not
+        yet been released.
+        
         Returns ``True`` if the condition is met, and ``False`` if the timeout
         is reached.
 
@@ -858,7 +866,15 @@ def wait_while(self, s, timeout=None):
         Blocks until ``s`` is not in ``self.state``.  The condition is checked
         when there is an I/O event related to the ``state`` attribute.  Exits
         early when ``timeout`` (in milliseconds) is reached.
-
+        
+        **Warning:** In ev3dev kernel release cycles 16 and earlier, there is
+        a bug which causes the ``state`` attribute to include ``stalled``
+        immediately after starting the motor even if it is not actually being
+        prevented from rotating. As a workaround, we recommend sleeping your
+        code for around 100ms after starting a motor if you are going to use
+        this method to wait for it to be ``stalled``. A fix for this has not
+        yet been released.
+        
         Returns ``True`` if the condition is met, and ``False`` if the timeout
         is reached.