Update and clarify installation instructions

- Always clarify that the instructions assume a virtual environment
- Add to the tutorial instructions for using venv
- Clarify that Python 3 is required
- Clarify that the tutorial is an alternative to "Getting started" that
assumes less background knowledge
- Remove pip installation instructions because Django only supports
versions of Python that include it
- Make headings in the tutorial instead of an ordered list
  This makes the page easier to scan visually and allows linking to
specific headings.
- Add the warning about Pillow dependencies to the tutorial
- In "Getting started" move Pillow's dependencies to the general
dependencies list
- Make language more welcoming (saying "we just do x" alienates people
who have less familiarity with x")
- Other small text changes

README.md

@@ -26,12 +26,15 @@ Find out more at [wagtail.io](https://wagtail.io/).
 
 ### Getting started
 
-Wagtail works with Python 3, on any platform.
+Wagtail works with [Python 3](https://www.python.org/downloads/), on any platform.
 
-```
+To get started with Wagtail, run the following in a virtual environment:
+
+``` bash
 pip install wagtail
 wagtail start mysite
 cd mysite
+pip install -r requirements.txt
 python manage.py migrate
 python manage.py createsuperuser
 python manage.py runserver

docs/getting_started/index.rst

@@ -1,43 +1,38 @@
 Getting started
 ===============
 
-Wagtail is built on the `Django web framework <https://www.djangoproject.com/>`_, so this document assumes you've already got the essentials installed. But if not, those essentials are:
+.. note::
+   These instructions assume familiarity with virtual environments and the `Django web framework <https://www.djangoproject.com/>`_. For more detailed instructions, see :doc:`tutorial`. To add Wagtail to an existing Django project, see :doc:`integrating_into_django`.
 
- * `Python <https://www.python.org/downloads/>`_
- * `pip <https://pip.pypa.io/en/latest/installing.html>`_ (Note that pip is included by default with Python 3.4 and later)
 
-We'd also recommend Virtualenv, which provides isolated Python environments:
+Dependencies needed for installation
+------------------------------------
 
- * `Virtualenv <https://virtualenv.pypa.io/en/latest/installation.html>`_
+* `Python 3 <https://www.python.org/downloads/>`_
+* **libjpeg** and **zlib**, libraries required for Django's **Pillow** library.
+  See Pillow's `platform-specific installation instructions <http://pillow.readthedocs.org/en/latest/installation.html#external-libraries>`_.
 
-.. important::
-   Before installing Wagtail, it is necessary to install the **libjpeg** and **zlib** libraries, which provide support for working with JPEG, PNG and GIF images (via the Python **Pillow** library). The way to do this varies by platform - see Pillow's `platform-specific installation instructions <http://pillow.readthedocs.org/en/latest/installation.html#external-libraries>`_.
 
-With the above installed, the quickest way to install Wagtail is:
-
-*If you are using Virtualenv, run*
-
-.. code-block:: console
-
-    $ virtualenv env -p python3
-    $ source env/bin/activate
+Quick install
+-------------
 
+Run the following in a virtual environment of your choice:
 
 .. code-block:: console
 
     $ pip install wagtail
 
-(``sudo`` may be required if installing system-wide or without virtualenv)
+(Installing outside a virtual environment may require ``sudo``.)
 
-Once installed, Wagtail provides a command similar to Django's ``django-admin startproject`` which stubs out a new site/project:
+Once installed, Wagtail provides a command similar to Django's ``django-admin startproject`` to stub out a new site/project:
 
 .. code-block:: console
 
     $ wagtail start mysite
 
-This will create a new folder ``mysite``, based on a template containing all you need to get started. More information on that template is available :doc:`here </reference/project_template>`.
+This will create a new folder ``mysite``, based on a template containing all you need to get started. More information on that template is available in :doc:`the project template reference </reference/project_template>`.
 
-Inside your ``mysite`` folder, we now just run the setup steps necessary for any Django project:
+Inside your ``mysite`` folder, run the setup steps necessary for any Django project:
 
 .. code-block:: console
 

docs/getting_started/tutorial.rst

@@ -4,13 +4,66 @@ Your first Wagtail site
 .. note::
    This tutorial covers setting up a brand new Wagtail project. If you'd like to add Wagtail to an existing Django project instead, see :doc:`integrating_into_django`.
 
-1. Install Wagtail and its dependencies:
+Install and run Wagtail
+-----------------------
+
+Install dependencies
+~~~~~~~~~~~~~~~~~~~~
+
+Wagtail supports Python 3.4, 3.5, 3.6, and 3.7.
+
+To check whether you have an appropriate version of Python 3:
+
+.. code-block:: console
+
+   $ python3 --version
+
+If this does not return a version number or returns a version before 3.4, you will need to `install Python 3 <https://www.python.org/downloads/>`_.
+
+.. important::
+   Before installing Wagtail, it is necessary to install the **libjpeg** and **zlib** libraries, which provide support for working with JPEG, PNG and GIF images (via the Python **Pillow** library).
+   The way to do this varies by platform—see Pillow's `platform-specific installation instructions <http://pillow.readthedocs.org/en/latest/installation.html#external-libraries>`_.
+
+
+Create and activate a virtual environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We recommend using a virtual environment, which provides an isolated Python environment. This tutorial uses `venv <https://docs.python.org/3/tutorial/venv.html>`_, which is packaged with Python 3.
+
+Create a virtual environment:
+
+.. code-block:: console
+
+   $ python3 -m venv mysite-env
+
+
+Activate your virtual environment:
+
+   On Windows:
+
+      .. code-block:: console
+
+         $ mysite-env\Scripts\activate.bat
+
+   On Unix or MacOS (bash):
+
+      .. code-block:: console
+
+         $ source mysite-env/bin/activate
+
+   For other shells, see the `venv documentation <https://docs.python.org/3/library/venv.html>`_.
+
+Install Wagtail
+~~~~~~~~~~~~~~~
+
+Use pip, which is packaged with Python, to install Wagtail and its dependencies:
 
 .. code-block:: console
 
    $ pip install wagtail
 
-2. Start your site:
+Generate your site
+~~~~~~~~~~~~~~~~~~
 
 .. code-block:: console
 
@@ -24,30 +77,34 @@ Your first Wagtail site
 "home" app with a blank ``HomePage`` model and basic templates and a sample
 "search" app.
 
-3. Install project dependencies:
+Install project dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: console
 
    $ pip install -r requirements.txt
 
-   This ensures that you have the relevant version of Django for the project you've just created.
+This ensures that you have the relevant version of Django and any other dependencies for the project you have just created.
 
-4. Create the database:
+Create the database
+~~~~~~~~~~~~~~~~~~~
+
+If you haven't updated the project settings, this will be a SQLite
+database file in the project directory.
 
 .. code-block:: console
 
    $ python manage.py migrate
 
-   If you haven't updated the project settings, this will be a SQLite
-   database file in the project directory.
-
-5. Create an admin user:
+Create an admin user
+~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: console
 
    $ python manage.py createsuperuser
 
-6. Start the server:
+Start the server
+~~~~~~~~~~~~~~~~
 
 .. code-block:: console