Sum documentation improvement from Mike getting-started session.

docs/source/coredev/index.rst

@@ -1,18 +1,28 b''
 .. _core_developer_guide:
 
 ==================================
-Developer's guide to core IPython
+Guide for IPtyhon core Developpers
 ==================================
 
 This guide documents the development of core IPython. Alternatively,
 developers of third party tools and libraries that use IPython should see the
 :doc:`../development/index`.
 
-Developers working on core IPython should also consult the
-`developer information <https://github.com/ipython/ipython/wiki/Dev:-Index>`_
-on the IPython GitHub wiki.
+
+For instruction on how to make a developer install see devinstall_.
 
 .. toctree::
    :maxdepth: 1
 
    release_process
+
+
+Old Documentation
+=================
+
+Out of date documentation is still available and have been kept for archival
+reason.
+
+Developers working on core IPython should also consult the
+`developer information <https://github.com/ipython/ipython/wiki/Dev:-Index>`_
+on the IPython GitHub wiki.

docs/source/install/install.rst

@@ -24,11 +24,13 b' install Jupyter ``pip install jupyter``.'
 Overview
 --------
 
-This document describes in detail the steps required to install IPython.
-For a few quick ways to get started with package managers or full Python distributions,
-see `the install page <http://ipython.org/install.html>`_ of the IPython website.
+This document describes in detail the steps required to install IPython. For a
+few quick ways to get started with package managers or full Python
+distributions, see `the install page <http://ipython.org/install.html>`_ of the
+IPython website.
 
-Please let us know if you have problems installing IPython or any of its dependencies.
+Please let us know if you have problems installing IPython or any of its
+dependencies.
 
 IPython and most dependencies should be installed via :command:`pip`.
 In many scenarios, this is the simplest method of installing Python packages.
@@ -39,13 +41,25 b' More information about :mod:`pip` can be found on'
 More general information about installing Python packages can be found in
 `Python's documentation <http://docs.python.org>`_.
 
+.. _dependencies:
+
+Dependencies
+~~~~~~~~~~~~
+
+IPython relies on a number of other Python packages. Installing using a package
+manager like pip or conda will ensure the necessary packages are installed. If
+you install manually, it's up to you to make sure dependencies are installed.
+They're not listed here since a static list would inevitably fall out of date as
+dependencies may change from release to release and also vary depending on
+the platform.
+
 
 Installing IPython itself
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 IPython requires several dependencies to work correctly, it is not recommended
-to install IPython and all its dependencies manually as this can be quite long and troublesome.
-You should use the python package manager ``pip``.
+to install IPython and all its dependencies manually as this can be quite long
+and troublesome. You should use the python package manager ``pip``.
 
 Installation using pip
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -76,40 +90,42 b' grab the latest stable tarball of IPython `from PyPI'
     $ cd ipython
     $ pip install .
 
-Do not invoke ``setup.py`` directly as this can have undesirable consequences for further upgrades. 
-Try to also avoid any usage of ``easy_install`` that can have similar undesirable consequences.
+Do not invoke ``setup.py`` directly as this can have undesirable consequences
+for further upgrades. Try to also avoid any usage of ``easy_install`` that can
+have similar undesirable consequences.
 
 If you are installing to a location (like ``/usr/local``) that requires higher
 permissions, you may need to run the last command with :command:`sudo`. You can
-also install in user specific location by using the ``--user`` flag in conjunction with pip.
+also install in user specific location by using the ``--user`` flag in
+conjunction with pip.
 
-To run IPython's test suite, use the :command:`iptest` command from outside of the IPython source tree:
+To run IPython's test suite, use the :command:`iptest` command from outside of
+the IPython source tree:
 
 .. code-block:: bash
 
     $ iptest
 
-
+.. _devinstall:
 Installing the development version
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 It is also possible to install the development version of IPython from our
 `Git <http://git-scm.com/>`_ source code repository.  To do this you will
-need to have Git installed on your system.  Then do:
-
-.. code-block:: bash
+need to have Git installed on your system.  
 
-    $ git clone https://github.com/ipython/ipython.git
-    $ cd ipython
-    $ pip install .
 
-Some users want to be able to follow the development branch as it changes.
-With :mod:`pip` installed, you can replace the last step by:
+Then do:
 
 .. code-block:: bash
 
+    $ git clone https://github.com/ipython/ipython.git
+    $ cd ipython
     $ pip install -e .
 
+The `pip install -e .` allow users and developers to be able to follow the
+development branch as it changes.
+
 This creates links in the right places and installs the command line script to
 the appropriate location. 
 
@@ -119,14 +135,3 b' Then, if you want to update your IPython at any time, do:'
 
     $ git pull
 
-.. _dependencies:
-
-Dependencies
-~~~~~~~~~~~~
-
-IPython relies on a number of other Python packages. Installing using a package
-manager like pip or conda will ensure the necessary packages are installed. If
-you install manually, it's up to you to make sure dependencies are installed.
-They're not listed here since a static list would inevitably fall out of date as
-dependencies may change from release to release and also vary depending on
-the platform.