DOC: add small caveat section in missing_data.rst

Author: cpcloud

doc/source/missing_data.rst

@@ -596,6 +596,31 @@ You can also operate on the DataFrame in place
 
    df.replace(1.5, nan, inplace=True)
 
+.. warning::
+
+   When replacing multiple ``bool`` or ``datetime64`` objects, the first 
+   argument to ``replace`` (``to_replace``) must match the type of the value
+   being replaced type. For example,
+
+   .. code-block::
+
+      s = Series([True, False, True])
+      s.replace({'a string': 'new value', True: False})
+
+   will raise a ``TypeError`` because one of the ``dict`` keys is not of the
+   correct type for replacement.
+
+   However, when replacing a *single* object such as,
+
+   .. code-block::
+
+      s = Series([True, False, True])
+      s.replace('a string', 'another string')
+
+   the original ``NDFrame`` object will be returned untouched. We're working on
+   unifying this API, but for backwards compatibility reasons we cannot break
+   the latter behavior. See :issue:`6354` for more details.
+
 Missing data casting rules and indexing
 ---------------------------------------