moar warnings

Author: jreback

doc/source/dsintro.rst

@@ -518,9 +518,24 @@ respects the order of the keyword arguments. You can use assign in the following
 
 .. warning::
 
-   This may subtly change the behavior of your code when you are
-   using :func:`DataFrame.assign` to update an existing column. Prior to Python 3.6,
-   callables referring to other variables being updated would get the "old" values.
+   Prior to Python 3.6, this may subtly change the behavior of your code when you are
+   using :func:`DataFrame.assign` to update an existing column.
+
+   Since the function signature of ``assign`` is ``**kwargs``, a dictionary,
+   the order of the new columns in the resulting DataFrame cannot be guaranteed
+   to match the order you pass in. To make things predictable, items are inserted
+   alphabetically (by key) at the end of the DataFrame.
+
+   .. ipython::
+      :verbatim:
+
+      In [1]: # Don't do this, bad reference to `C`
+              df.assign(C = lambda x: x['A'] + x['B'],
+                        D = lambda x: x['A'] + x['C'])
+      In [2]: # Instead, break it into two assigns
+              (df.assign(C = lambda x: x['A'] + x['B'])
+                 .assign(D = lambda x: x['A'] + x['C']))
+
 
 Indexing / Selection
 ~~~~~~~~~~~~~~~~~~~~