diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index 32a1d66..67ebd8e 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -196,8 +196,8 @@
    .. warning::
 
       This will deadlock if the child process generates enough output to a
-      stdout or stderr pipe causing it to block waiting for the OS's pipe buffer
-      to accept more data.
+      stdout or stderr pipe such that it blocks waiting for the OS pipe buffer
+      to accept more data.  Use :meth:`communicate` to avoid that.
 
 
 .. method:: Popen.communicate(input=None)
@@ -253,9 +253,10 @@
 
 .. warning::
 
-   Use :meth:`communicate` rather than ``.stdin.write()``, ``.stdout.read()`` or
-   ``.stderr.read`` to avoid deadlocks due to any of the other pipe buffers
-   filling up and blocking the child process.
+   Use :meth:`communicate` rather than :meth:`.stdin.write`,
+   :meth:`.stdout.read` or :meth:`.stderr.read` to avoid deadlocks due
+   to any of the other OS pipe buffers filling up and blocking the child
+   process.
 
 
 .. attribute:: Popen.stdin