diff -r a969b42e6e2b Doc/library/asyncio-stream.rst
--- a/Doc/library/asyncio-stream.rst	Sat Sep 06 20:40:00 2014 +1000
+++ b/Doc/library/asyncio-stream.rst	Sat Sep 06 14:43:39 2014 +0200
@@ -170,7 +170,7 @@
 
    .. method:: drain()
 
-      Wait until the write buffer of the underlying transport is flushed.
+      Let the write buffer of the underlying transport a chance to be flushed.
 
       The intended use is to write::
 
@@ -181,6 +181,11 @@
       the buffer is (partially) drained and the protocol is resumed. When there
       is nothing to wait for, the yield-from continues immediately.
 
+      Yielding from `drain()` gives the opportunity for the loop to schedule
+      the write operation and flush the buffer. It should especially be used
+      when a possibly large amount of data is written to the transport,
+      and the coroutine does not yield-from between calls to `write*()`.
+
       This method is a :ref:`coroutine <coroutine>`.
 
    .. method:: get_extra_info(name, default=None)