diff --git a/doc/users/image_tutorial.rst b/doc/users/image_tutorial.rst
index 6cff4b03f273..5e9ac0d05758 100644
--- a/doc/users/image_tutorial.rst
+++ b/doc/users/image_tutorial.rst
@@ -10,26 +10,17 @@ Image tutorial
 Startup commands
 ===================
 
-At the very least, you'll need to have access to the
-:func:`~matplotlib.pyplot.imshow` function.  There are a couple of
-ways to do it.  The easy way for an interactive environment::
-
+In this tutorial we will work interactively with images. To do so we will use
+the IPython shell. You can start it with::
+    
     $ipython
 
-to enter the ipython shell, followed by::
-
-    In [1]: %pylab
-
-to enter the pylab environment.
-
-The imshow function is now directly accessible (it's in your
-`namespace <http://bytebaker.com/2008/07/30/python-namespaces/>`_).
-See also :ref:`pyplot-tutorial`.
-
-The more expressive, easier to understand later method (use this in
-your scripts to make it easier for others (including your future self)
-to read) is to use the matplotlib API (see :ref:`artist-tutorial`)
-where you use explicit namespaces and control object creation, etc...
+At the very least, you'll need to have access to the
+:func:`~matplotlib.pyplot.imshow` function. The easy way for an interactive
+environment: is to use the matplotlib API (see :ref:`artist-tutorial`) where
+you use explicit 
+`namespaces <http://bytebaker.com/2008/07/30/python-namespaces/>`_ and control 
+object creation, etc...::
 
 .. sourcecode:: ipython
 
@@ -37,9 +28,10 @@ where you use explicit namespaces and control object creation, etc...
    In [2]: import matplotlib.image as mpimg
    In [3]: import numpy as np
 
-Examples below will use the latter method, for clarity.  In these
-examples, if you use the %pylab method, you can skip the "mpimg." and
-"plt." prefixes.
+You can now access functions like :func:`~matplotlib.pyplot.imshow` by using:
+`plt.imshow(yourimage)`. You can learn more about these functions in the
+:ref:`pyplot-tutorial`.
+
 
 .. _importing_data:
 
diff --git a/doc/users/shell.rst b/doc/users/shell.rst
index e8d36586118c..20c465895fe6 100644
--- a/doc/users/shell.rst
+++ b/doc/users/shell.rst
@@ -20,9 +20,19 @@ python shell.
 
 .. _ipython-pylab:
 
-Ipython to the rescue
+IPython to the rescue
 =====================
 
+.. note::
+
+    The mode described here still exists for historical reasons, but it is
+    highly advised not to use. It pollutes namespaces with functions that will
+    shadow python built-in and can lead to hard to track bugs. To get IPython
+    integration without imports the use of the  `%matplotlib` magic is
+    preferred. See
+    `ipython documentation <http://ipython.org/ipython-doc/stable/interactive/reference.html#plotting-with-matplotlib>`_
+    .
+
 Fortunately, `ipython <http://ipython.org/>`_, an enhanced
 interactive python shell, has figured out all of these tricks, and is
 matplotlib aware, so when you start ipython in the *pylab* mode.