diff --git a/README.md b/README.md
index 7b85842bb2..71763d82a7 100644
--- a/README.md
+++ b/README.md
@@ -26,15 +26,18 @@ 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.
-```
- pip install wagtail
- wagtail start mysite
- cd mysite
- python manage.py migrate
- python manage.py createsuperuser
- python manage.py runserver
+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
```
For detailed installation and setup docs, see [docs.wagtail.io](http://docs.wagtail.io/).
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
index 1d06a535cb..2b19b66f25 100644
--- a/docs/getting_started/index.rst
+++ b/docs/getting_started/index.rst
@@ -1,43 +1,38 @@
Getting started
===============
-Wagtail is built on the `Django web framework `_, 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 `_. For more detailed instructions, see :doc:`tutorial`. To add Wagtail to an existing Django project, see :doc:`integrating_into_django`.
- * `Python `_
- * `pip `_ (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 `_
+* `Python 3 `_
+* **libjpeg** and **zlib**, libraries required for Django's **Pillow** library.
+ See Pillow's `platform-specific installation instructions `_.
-.. 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 `_.
-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 `.
+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 `.
-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
diff --git a/docs/getting_started/tutorial.rst b/docs/getting_started/tutorial.rst
index af210431b7..f45952ef61 100644
--- a/docs/getting_started/tutorial.rst
+++ b/docs/getting_started/tutorial.rst
@@ -4,64 +4,121 @@ 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
+-----------------------
- .. code-block:: console
+Install dependencies
+~~~~~~~~~~~~~~~~~~~~
- $ pip install wagtail
+Wagtail supports Python 3.4, 3.5, 3.6, and 3.7.
-2. Start your site:
+To check whether you have an appropriate version of Python 3:
- .. code-block:: console
+.. code-block:: console
- $ wagtail start mysite
- $ cd mysite
+ $ python3 --version
- Wagtail provides a ``start`` command similar to
- ``django-admin.py startproject``. Running ``wagtail start mysite`` in
- your project will generate a new ``mysite`` folder with a few
- Wagtail-specific extras, including the required project settings, a
- "home" app with a blank ``HomePage`` model and basic templates and a sample
- "search" app.
+If this does not return a version number or returns a version before 3.4, you will need to `install Python 3 `_.
-3. Install project dependencies:
+.. 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 `_.
- .. code-block:: console
- $ pip install -r requirements.txt
+Create and activate a virtual environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- This ensures that you have the relevant version of Django for the project you've just created.
+We recommend using a virtual environment, which provides an isolated Python environment. This tutorial uses `venv `_, which is packaged with Python 3.
-4. Create the database:
+Create a virtual environment:
- .. code-block:: console
+.. code-block:: console
- $ python manage.py migrate
+ $ python3 -m venv mysite-env
- If you haven't updated the project settings, this will be a SQLite
- database file in the project directory.
-5. Create an admin user:
+Activate your virtual environment:
- .. code-block:: console
+ On Windows:
- $ python manage.py createsuperuser
+ .. code-block:: console
-6. Start the server:
+ $ mysite-env\Scripts\activate.bat
- .. code-block:: console
+ On Unix or MacOS (bash):
- $ python manage.py runserver
+ .. code-block:: console
- If everything worked, http://127.0.0.1:8000 will show you a welcome page:
+ $ source mysite-env/bin/activate
- .. figure:: ../_static/images/tutorial/tutorial_1.png
- :alt: Wagtail welcome message
+ For other shells, see the `venv documentation `_.
- You can now access the administrative area at http://127.0.0.1:8000/admin
+Install Wagtail
+~~~~~~~~~~~~~~~
- .. figure:: ../_static/images/tutorial/tutorial_2.png
- :alt: Administrative screen
+Use pip, which is packaged with Python, to install Wagtail and its dependencies:
+
+.. code-block:: console
+
+ $ pip install wagtail
+
+Generate your site
+~~~~~~~~~~~~~~~~~~
+
+.. code-block:: console
+
+ $ wagtail start mysite
+ $ cd mysite
+
+Wagtail provides a ``start`` command similar to
+``django-admin.py startproject``. Running ``wagtail start mysite`` in
+your project will generate a new ``mysite`` folder with a few
+Wagtail-specific extras, including the required project settings, a
+"home" app with a blank ``HomePage`` model and basic templates and a sample
+"search" app.
+
+Install project dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: console
+
+ $ pip install -r requirements.txt
+
+This ensures that you have the relevant version of Django and any other dependencies for the project you have just created.
+
+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
+
+Create an admin user
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: console
+
+ $ python manage.py createsuperuser
+
+Start the server
+~~~~~~~~~~~~~~~~
+
+.. code-block:: console
+
+ $ python manage.py runserver
+
+If everything worked, http://127.0.0.1:8000 will show you a welcome page:
+
+.. figure:: ../_static/images/tutorial/tutorial_1.png
+ :alt: Wagtail welcome message
+
+You can now access the administrative area at http://127.0.0.1:8000/admin
+
+.. figure:: ../_static/images/tutorial/tutorial_2.png
+ :alt: Administrative screen
Extend the HomePage model
-------------------------