Update quickstart guide to reflect user research

docs/html/quickstart.rst

@@ -2,90 +2,150 @@
 Quickstart
 ==========
 
-First, :doc:`install pip <installing>`.
+pip is a command line tool for installing Python packages.
 
-Install a package from `PyPI`_:
+For a full tutorial on installing packages with pip, see the
+`Python Packaging User Guide`_
+
+For a more detailed exploration of pip's functionality see the pip
+:doc:`user guide <user_guide>`.
+
+Quick setup
+===========
+
+1. Check pip installation
+-------------------------
+Check if you already have pip installed by running:
 
 .. tab:: Unix/macOS
 
    .. code-block:: console
 
-      $ python -m pip install SomePackage
-      [...]
-      Successfully installed SomePackage
+      $ python -m pip --version
 
 .. tab:: Windows
 
    .. code-block:: console
 
-      C:\> py -m pip install SomePackage
-      [...]
-      Successfully installed SomePackage
+      C:\> py -m pip --version
+
+See :doc:`installing pip <installing>` for more information, or to troubleshoot
+any problems.
 
+2. Check pip is up to date
+--------------------------
 
-Install a package that's already been downloaded from `PyPI`_ or
-obtained from elsewhere. This is useful if the target machine does not have a
-network connection:
+To make sure you are running pip's latest version, run:
 
 .. tab:: Unix/macOS
 
    .. code-block:: console
 
-      $ python -m pip install SomePackage-1.0-py2.py3-none-any.whl
+      python -m pip install -U pip
+
+.. tab:: Windows
+
+   .. code-block:: console
+
+      py -m pip install -U pip
+
+
+3. Set up a virtual environment
+-------------------------------
+
+Before using pip, we recommend you set up and use a virtual environment to
+isolate your project packages.
+
+See `Creating Virtual Environments`_ for more information.
+
+Common tasks
+============
+
+Install a package from `PyPI`_
+------------------------------
+
+.. tab:: Unix/macOS
+
+   .. code-block:: console
+
+      $ python -m pip install SomePackage
       [...]
       Successfully installed SomePackage
 
 .. tab:: Windows
 
    .. code-block:: console
 
-      C:\> py -m pip install SomePackage-1.0-py2.py3-none-any.whl
+      C:\> py -m pip install SomePackage
       [...]
       Successfully installed SomePackage
 
-Show what files were installed:
+Install a package from GitHub
+------------------------------
+
+Pip can install packages from common version control systems (VCS), including
+GitHub.
+
+For example, to install a specific commit from the Django project, run:
 
 .. tab:: Unix/macOS
 
    .. code-block:: console
 
-      $ python -m pip show --files SomePackage
-      Name: SomePackage
-      Version: 1.0
-      Location: /my/env/lib/pythonx.x/site-packages
-      Files:
-      ../somepackage/__init__.py
-      [...]
+      $ python -m pip install git+https://github.com/django/django.git@45dfb3641aa4d9828a7c5448d11aa67c7cbd7966
 
 .. tab:: Windows
 
    .. code-block:: console
 
-      C:\> py -m pip show --files SomePackage
-      Name: SomePackage
-      Version: 1.0
-      Location: /my/env/lib/pythonx.x/site-packages
-      Files:
-      ../somepackage/__init__.py
-      [...]
+      C:\> py -m pip install git+https://github.com/django/django.git@45dfb3641aa4d9828a7c5448d11aa67c7cbd7966
+
+See :ref:`VCS Support` for more information.
+
+Install a package you have already downloaded
+---------------------------------------------
 
-List what packages are outdated:
+This is useful if the target machine does not have a network connection:
 
 .. tab:: Unix/macOS
 
    .. code-block:: console
 
-      $ python -m pip list --outdated
-      SomePackage (Current: 1.0 Latest: 2.0)
+      $ python -m pip install SomePackage-1.0-py2.py3-none-any.whl
+      [...]
+      Successfully installed SomePackage
 
 .. tab:: Windows
 
    .. code-block:: console
 
-      C:\> py -m pip list --outdated
-      SomePackage (Current: 1.0 Latest: 2.0)
+      C:\> py -m pip install SomePackage-1.0-py2.py3-none-any.whl
+      [...]
+      Successfully installed SomePackage
+
+Install packages from requirements.txt
+--------------------------------------
+
+Many Python projects use a requirements.txt file to specify the list of packages
+that need to be installed for the project to run. To install the packages
+listed in the file, run:
+
+  .. tab:: Unix/macOS
+
+     .. code-block:: console
 
-Upgrade a package:
+        $ python -m pip install -r requirements.txt
+
+  .. tab:: Windows
+
+     .. code-block:: console
+
+        C:\> py -m pip install -r requirements.txt
+
+See :ref:`requirements files <Requirements Files>` for more information.
+
+Upgrade a package
+-----------------
 
 .. tab:: Unix/macOS
 
@@ -111,7 +171,8 @@ Upgrade a package:
       Running setup.py install for SomePackage
       Successfully installed SomePackage
 
-Uninstall a package:
+Uninstall a package
+-------------------
 
 .. tab:: Unix/macOS
 
@@ -133,4 +194,9 @@ Uninstall a package:
       Proceed (y/n)? y
       Successfully uninstalled SomePackage
 
+For a full list of pip commands, see the pip
+:doc:`reference guide <reference/index>`.
+
 .. _PyPI: https://pypi.org/
+.. _Python Packaging User Guide: https://packaging.python.org/tutorials/installing-packages
+.. _Creating Virtual Environments: https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments