Clarify kernel installation instructions

Alternative to gh-9154

docs/source/conf.py

@@ -206,6 +206,7 b" intersphinx_mapping = {'python': ('http://docs.python.org/2/', None),"
                        'traitlets': ('http://traitlets.readthedocs.org/en/latest/', None),
                        'jupyterclient': ('http://jupyter-client.readthedocs.org/en/latest/', None),
                        'ipyparallel': ('http://ipyparallel.readthedocs.org/en/latest/', None),
+                       'jupyter': ('http://jupyter.readthedocs.org/en/latest/', None),
                       }
 
 # Options for LaTeX output

docs/source/install/kernel_install.rst

@@ -3,37 +3,51 b''
 Installing the IPython kernel
 =============================
 
+.. seealso::
+
+   :ref:`Installing Jupyter <jupyter:install>`
+     The IPython kernel is the Python execution backend for Jupyter.
+
 The Jupyter Notebook and other frontends automatically ensure that the IPython kernel is available.
 However, if you want to use a kernel with a different version of Python, or in a virtualenv or conda environment,
 you'll need to install that manually.
 
-Using the Python version or environment for which you want to set up the kernel, run::
+Kernels for Python 2 and 3
+--------------------------
+
+If you're running Jupyter on Python 3, you can set up a Python 2 kernel like this::
+
+    python2 -m pip install ipykernel
+    python2 -m ipykernel install --user
 
-    pip install ipykernel  # or: conda install ipykernel
+Or using conda, create a Python 2 environment::
+
+    conda create -n ipykernel_py2 python=2 ipykernel
+    source activate ipykernel_py2    # On Windows, remove the word 'source'
     python -m ipykernel install --user
 
+If you're running Jupyter on Python 2 and want to set up a Python 3 kernel,
+follow the same steps, replacing ``2`` with ``3``.
+
 The last command installs a :ref:`kernel spec <jupyterclient:kernelspecs>` file
 for the current python installation. Kernel spec files are JSON files, which
 can be viewed and changed with a normal text editor.
 
-See `python -m ipykernel install --help` for the list of installation options like
-naming the kernel, or non default install location.
-
 .. _multiple_kernel_install:
 
-Multiple IPython installations
-==============================
+Kernels for different environments
+----------------------------------
 
-If you want to have multiple IPython kernels for different environments,
-you will need to specify unique names for the kernelspecs,
-and you may also want to specify the display name of those kernels,
-so that you can clearly see which is which in the notebook menus:
+If you want to have multiple IPython kernels for different virtualenvs or conda environments,
+you will need to specify unique names for the kernelspecs:
 
 .. sourcecode:: bash
 
     source activate myenv
-    ipython kernel install --user --name myenv --display-name "Python (myenv)"
+    python -m ipykernel install --user --name myenv --display-name "Python (myenv)"
     source activate other-env
-    ipython kernel install --user --name other-env --display-name "Python (other-env)"
-    source deactivate
+    python -m ipykernel install --user --name other-env --display-name "Python (other-env)"
 
+The ``--name`` value is used by Jupyter internally. These commands will overwrite
+any existing kernel with the same name. ``--display-name`` is what you see in
+the notebook menus.