Improve installation sections (#23)

* Clean up the distiction between astroconda and iraf27, etc

* Be more direct with IRAF users; Added architecture footnote; Wording.

* Add new line

* Fix word salad

* Shell environment wording

source/installation.rst

@@ -2,26 +2,27 @@
 Installation
 ############
 
-Before you begin, note the following requirements and limitations of AstroConda:
+Before you begin, the list below contains known requirements and limitations of AstroConda:
 
+    - This documentation targets Anaconda3 (i.e. Python 3)
     - AstroConda supports Linux (glibc ≥ 2.12) and Mac OS X (≥ 10.7; 10.6 is NOT supported)
-    - AstroConda packages support Python versions 2.7 or 3.5 on 64-bit platforms. (If you don't know whether you have a 32-bit or 64-bit processor, assume you have 64-bit.)
-    - If :abbr:`IRAF (Image Reduction and Analysis Facility)` is required as part of your personal workflow it is *highly recommended* you install Anaconda for Python 2.7 (see :ref:`iraf_python3`).
-    - If you do not use :abbr:`IRAF (Image Reduction and Analysis Facility)`, choose the Anaconda installer with the Python version best suited for your scripting needs.
-    - This documentation specifically targets Anaconda for Python 3 installations. However, the same commands should still work interchangeably between versions.
+    - AstroConda contains packages for 64-bit [#archnote]_ Python 2.7 and 3.5.
+    - Conda only supports BASH and ZSH environments. If you are a native CSH user, execute ``bash -l`` prior to performing the procedures detailed in this guide.
+    - IRAF users: After configuring Anaconda for use with AstroConda, refer to the :ref:`iraf_install` section of this guide to continue your installation.
 
 Obtain Anaconda
 ===============
 
-Go grab a copy of the `Anaconda <https://www.continuum.io/downloads>`_ distribution from Continuum Analytics, Inc. Be sure to select the installation medium appropriate for your operating system (Linux or OS X) and architecture (64-bit). The OS X GUI installer may cause side-effects, such as changing permissions of files in your home directory to ``root:wheel``, or mistakenly creating a system-wide installation in ``/anaconda`` instead of your personal home directory. To avoid this situation perform a command-line installation instead.
+.. note::
 
-Follow the installation instructions for your platform given on the download page. Before moving on to the next step, open a new terminal window, run the ``conda`` command, and ensure your terminal can find it.
+    Installing Anaconda3 will not prevent you from using Python 2.
 
-.. note::
+    ``conda`` allows you to to deploy multiple independent Python environments, at-will, under a single Anaconda installation. You may have trouble following along with this guide if you choose to install Anaconda2.
 
-    Are you using ``bash`` as your shell? Run ``echo $SHELL`` in a terminal and make sure it says something like ``/bin/bash``. If it does not, you will have to change your default shell (which is outside the scope of these instructions).
 
-    In the meantime, you can start ``bash -l`` from within your terminal to use ``bash`` temporarily to follow these instructions.
+Go grab a copy of `Anaconda3 <https://www.continuum.io/downloads>`_ from Continuum Analytics, Inc. Be sure to select the installation medium appropriate for your operating system (Linux or OS X) and architecture (64-bit). The OS X GUI installer may cause side-effects, such as changing permissions of files in your home directory to ``root:wheel``, or mistakenly creating a system-wide installation under ``/anaconda`` instead of your personal home directory. To avoid this situation perform a command-line installation instead.
+
+Follow the installation instructions for your platform provided on the download page. Before moving on to the next step, open a new terminal window, and run ``conda`` to verify your terminal session can find it.
 
 
 Configure Conda
@@ -38,16 +39,16 @@ In order to install packages directly from the AstroConda repository, you will n
 Install AstroConda
 ==================
 
-Standard installation (without IRAF)
+Standard Installation (without IRAF)
 ------------------------------------
 
-Now that Conda is configured to pull from our repository, you may now go ahead and install the ``stsci`` metapackage. The example below will generate a new environment called "astroconda" (using the ``-n`` flag), however, this is merely a suggestion. Feel free to use a name that works best for you.
+Now that Conda is configured to pull from our repository, you may go ahead and install the ``stsci`` metapackage. The example below generates a new conda environment named "astroconda", however, this naming convention is merely a suggestion. Feel free to use a name that works best for you.
 
 .. code-block:: sh
 
     $ conda create -n astroconda stsci
 
-This will prompt you to confirm the installation of all the STScI packages available in AstroConda. Once they are installed, the following command "activates" the astroconda environment, making these packages available to you.
+This will prompt you to confirm the installation of all the STScI packages available in AstroConda. After they are installed, the following command "activates" the astroconda environment, making these packages available to you.
 
 .. code-block:: sh
 
@@ -57,29 +58,29 @@ This will prompt you to confirm the installation of all the STScI packages avail
 
     Though it is repeated a lot in examples, ``source activate astroconda`` only needs to be run once per terminal session. Running this command ensures subsequent commands will take effect only in the ``astroconda`` environment, keeping your system organized.
 
-    To deactivate the ``astroconda`` environment, close your terminal window or run ``source deactivate astroconda``.
+    To deactivate the ``astroconda`` environment, close your terminal window or run ``source deactivate``.
 
 
-Installation with legacy IRAF support
--------------------------------------
+.. _iraf_install:
 
-The developers of AstroConda have limited resources to support :abbr:`IRAF (Image Reduction and Analysis Facility)`, but users that require the ability to run IRAF and PyRAF tasks may want to install it through AstroConda. For help with many issues that come up during installation or use, visit the `PyRAF FAQ <http://www.stsci.edu/institute/software_hardware/pyraf/pyraf_faq>`_ page.
+Legacy Installation (with IRAF)
+-------------------------------------
 
-IRAF is not installed by default, so the AstroConda install command is a little different.
+The developers of AstroConda have limited resources to support :abbr:`IRAF (Image Reduction and Analysis Facility)`, but users that require the ability to run IRAF and PyRAF tasks may want to install it through AstroConda. For help with many issues that come up during installation or use, please visit the `PyRAF FAQ <http://www.stsci.edu/institute/software_hardware/pyraf/pyraf_faq>`_.
 
 .. code-block:: sh
 
-    $ conda create -n astroconda python=2.7 iraf pyraf stsci
+    $ conda create -n iraf27 python=2.7 iraf pyraf stsci
 
 Then, just as with the default installation, it is necessary to activate the environment to make its commands and packages available.
 
 .. code-block:: sh
 
-    $ source activate astroconda
+    $ source activate iraf27
 
 .. note::
 
-    Support for using Python 2.7 and IRAF is being gradually phased out by STScI maintainers. In the transitional period, you may wish to install AstroConda with the default settings but maintain a Python 2.7 + IRAF environment for testing. The following commands create an ``astroconda`` environment with the default settings, and an ``iraf27`` environment with IRAF.
+    Support for using Python 2.7 and IRAF is being gradually phased out by STScI maintainers. In the transitional period, you may wish to install AstroConda with the default settings but maintain a Python 2.7 + IRAF environment for testing. The following commands create both an ``astroconda`` environment with the default settings, and ``iraf27`` environment with IRAF.
 
     .. code-block:: sh
 
@@ -88,7 +89,7 @@ Then, just as with the default installation, it is necessary to activate the env
 
     Then, simply ``source activate astroconda`` for day-to-day use or ``source activate iraf27`` for work that requires IRAF. These two environments will be managed separately, allowing you to update only one or the other (see :doc:`updating`).
 
-Fine-tuning the installation
+Fine-tuning the Installation
 ============================
 
 If you are short on hard drive space, have a slow internet connection, or are simply not interested in installing *everything but the kitchen sink*; please feel free to peruse the `manifest <http://ssb.stsci.edu/astroconda>`_ and install a custom mix of packages tailored to your needs.
@@ -98,7 +99,7 @@ If you are short on hard drive space, have a slow internet connection, or are si
     $ conda create -n astroconda [package [package ...]]
     $ source activate astroconda
 
-Installing other packages
+Installing Other Packages
 =========================
 
 AstroConda provides a suite of packages that are known to work well together and are supported by engineers from STScI. However, being built on top of the widely-used ``conda`` tools for managing Python environments, AstroConda also supports the installation of additional 3rd-party packages.
@@ -110,7 +111,7 @@ For scientific packages available through Anaconda, installation is as simple as
 .. code-block:: sh
 
     $ source activate astroconda
-    $ conda install nameofpkg
+    $ conda install name_of_pkg
 
 Often, the easiest way to see if the package is available through Anaconda is to try installing it. The full list of available packages is here: http://repo.continuum.io/pkgs/.
 
@@ -119,5 +120,8 @@ The Python-standard tool ``pip`` is also available to install packages distribut
 .. code-block:: sh
 
     $ source activate astroconda
-    $ pip install nameofpkg
+    $ pip install name_of_pkg
+
+.. rubric:: Footnotes
 
+.. [#archnote] Intel x86_64 architecture