diff --git a/README.md b/README.md
index 3c25f04..a9fafba 100644
--- a/README.md
+++ b/README.md
@@ -20,53 +20,28 @@ subsystems of the Linux kernel. Although Patchwork has been developed with the
 kernel workflow in mind, the aim is to be flexible enough to suit the majority
 of community projects.
 
-# Development Installation using Vagrant
+# Development Installation
 
-1. Install [**Vagrant**][ref-vagrant]
-2. Clone this repo:
+[Docker][ref-docker] is the recommended installation methods for a Patchwork
+development environment. To install Patchwork:
 
-        $ git clone git://github.com/getpatchwork/patchwork.git
+1. Install [**Docker**][ref-docker] and [**docker-compose**][ref-compose].
+2. Clone the Patchwork repo:
 
-3. Run `vagrant up`:
+        $ git clone https://github.com/getpatchwork/patchwork.git
 
-        $ cd patchwork
-        $ vagrant up
-
-# Development Installation using Docker
-
-1. Install Docker and docker-compose.
-2. Clone this repo, as with vagrant.
 3. Build the images. This will download over 200MB from the internet:
 
         $ docker-compose build
 
-4. Run as follows:
-
-  * Regular server:
-
-          $ docker-compose up
-
-    This will be visible on http://localhost:8000/.
-
-  * Shell:
-
-          $ docker-compose run --rm web --shell
-
-  * Quick test (not including selenium UI interaction tests):
-
-          $ docker-compose run --rm web --quick-test
-
-  * Full tests, including selenium, run headlessly:
-
-          $ docker-compose run --rm web --test
-
-  * To reset the database before beginning, add `--reset` to the command line after `web` and before any other arguments.
+4. Run `docker-compose up`:
 
-  * If you want to run non-headless tests, you'll need something like this ugly hack:
+        $ docker-compose up
 
-          $ docker run -it --rm -v (pwd):/home/patchwork/patchwork/ --link patchwork_db_1:db -p 8000:8000 -v /tmp/.X11-unix:/tmp/.X11-unix -e PW_TEST_DB_HOST=db -e DISPLAY patchwork_web bash
+The Patchwork instance will now be deployed at `http://localhost:8000/`.
 
-With both vagrant and docker, any edits to the project files made locally are immediately visible to the VM/container, and so should be picked up by the Django auto-reloader.
+For more information, including alternative installation methods, refer to the
+[development installation guide][docs-development].
 
 # Talks and Presentations
 
@@ -90,7 +65,9 @@ For bug reports, patch submissions or other questions, please use the
 [badge-waffle-ref]: https://waffle.io/getpatchwork/patchwork
 [badge-waffle-img]: https://badge.waffle.io/getpatchwork/patchwork.svg?label=ready&title=Ready
 [docs]: https://patchwork.readthedocs.org/en/latest/
+[docs-development]: https://patchwork.readthedocs.org/en/latest/development/
 [pdf-fosdem]: https://speakerdeck.com/stephenfin/a-new-patchwork-bringing-ci-patch-tracking-and-more-to-the-mailing-list
 [pdf-plumbers]: https://www.linuxplumbersconf.org/2011/ocw/system/presentations/255/original/patchwork.pdf
 [pw-ml]: https://ozlabs.org/mailman/listinfo/patchwork
-[ref-vagrant]: https://www.vagrantup.com/docs/getting-started/
+[ref-compose]: https://docs.docker.com/compose/install/
+[ref-docker]: https://docs.docker.com/engine/installation/linux/
diff --git a/docs/development.md b/docs/development.md
index 593eddf..eaf3182 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -9,21 +9,70 @@ To begin, you should clone Patchwork:
 
     $ git clone git://github.com/getpatchwork/patchwork.git
 
+## Docker-Based Installation
+
+Patchwork provides a Docker-based environment for quick configuration of a
+development environment. This is the preferred installation method. To
+configure Patchwork using Docker:
+
+1. Install [**Docker**][ref-docker] and [**docker-compose**][ref-compose].
+2. Build the images. This will download over 200MB from the internet:
+
+        $ docker-compose build
+
+3. Run `docker-compose up`:
+
+        $ docker-compose up
+
+    This will be visible at http://localhost:8000/.
+
+To run a shell within this environment, run:
+
+    $ docker-compose run --rm web --shell
+
+To run unit tests, excluding Selenium UI interaction tests, run:
+
+    $ docker-compose run --rm web --quick-test
+
+To run all tests, including Selenium run headlessly, run:
+
+    $ docker-compose run --rm web --test
+
+To run all tests in non-headless tests:
+
+    $ docker run -it --rm -v (pwd):/home/patchwork/patchwork/ \
+        --link patchwork_db_1:db -p 8000:8000 \
+        -v /tmp/.X11-unix:/tmp/.X11-unix \
+        -e PW_TEST_DB_HOST=db -e DISPLAY patchwork_web bash
+
+To reset the database before any of these commands, add `--reset` to the
+command line after `web` and before any other arguments.
+
+Any local edits to the project files made locally are immediately visible to
+the Docker container, and so should be picked up by the Django auto-reloader.
+
+For more information on Docker itself, please refer to the [Docker][ref-docker]
+and [docker-compose][ref-compose] documentation.
+
 ## Vagrant-Based Installation
 
-Patchwork provides a Vagrantfile that can be used to quickly configure
-Patchwork in a development environment. Like any Vagrant VM, you can start this
-using the `vagrant up` command:
+Patchwork provides a Vagrant-based environment as an alternative to Docker.
+Like Docker, Vagrant can be used to quickly configure Patchwork in a
+development environment. To configure Patchwork using Vagrant:
+
+1. Install [**Vagrant**][ref-vagrant]
+2. Run `vagrant up` from the project directory:
 
-    $ cd patchwork  # the path to the repo you cloned above
-    $ vagrant up
+        $ cd patchwork
+        $ vagrant up
 
 Once stacked, follow the on-screen instructions. For more information on
-Vagrant itself, please refer to the [Vagrant documentation](ref-vagrant).
+Vagrant itself, please refer to the [Vagrant documentation][ref-vagrant].
 
 ## Manual Installation
 
-Manual installation can be used where Vagrant is not possible, or not desired.
+Manual installation can be used where use of Docker or Vagrant is not possible or
+desired.
 
 ### Install Required Packages
 
@@ -260,5 +309,7 @@ using the provided `dev` settings file.
 [ref-py34-pip]: http://legacy.python.org/dev/peps/pep-0453/
 [ref-sqlite-utf8]: https://www.sqlite.org/faq.html#q18
 [ref-tox]: https://tox.readthedocs.org/en/latest/
+[ref-compose]: https://docs.docker.com/compose/install/
+[ref-docker]: https://docs.docker.com/engine/installation/linux/
 [ref-vagrant]: https://www.vagrantup.com/docs/getting-started/
 [ref-venv]: https://virtualenv.readthedocs.org/en/latest/
