diff --git a/Doc/library/mmap.rst b/Doc/library/mmap.rst
--- a/Doc/library/mmap.rst
+++ b/Doc/library/mmap.rst
@@ -21,6 +21,11 @@
 :func:`os.open` function, which returns a file descriptor directly (the file
 still needs to be closed when done).
 
+..note::
+   If you want to create a memory-mapping for a writable, buffered file, you
+   should :func:`flush` the file first.  This is necessary to ensure that local
+   modifications to the buffers are actually available to the mapping.
+
 For both the Unix and Windows versions of the constructor, *access* may be
 specified as an optional keyword parameter. *access* accepts one of three
 values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY`