diff --git a/README.md b/README.md
index dcfb5f5d..36f55cd0 100644
--- a/README.md
+++ b/README.md
@@ -3,9 +3,11 @@
[![Build Status](https://travis-ci.org/jupyter/repo2docker.svg?branch=master)](https://travis-ci.org/jupyter/repo2docker)
[![Documentation Status](https://readthedocs.org/projects/repo2docker/badge/?version=latest)](http://repo2docker.readthedocs.io/en/latest/?badge=latest)
-
-**jupyter-repo2docker** is a tool to build, run and push docker images from source code repositories.
+**jupyter-repo2docker** is a tool to build, run and push Docker images from source code repositories.
+
+See the [repo2docker documentation](http://repo2docker.readthedocs.io)
+for more information.
## Pre-requisites
@@ -55,49 +57,13 @@ After building (it might take a while!), it should output in your terminal somet
If you copy paste that URL into your browser you will see a Jupyter Notebook with the
contents of the repository you had just built!
-### Displaying the image Dockerfile
-Repo2Docker will generate a Dockerfile that composes the created Docker image.
-To see the contents of this Dockerfile without building the image use `--debug` and `--no-build`
-flags like so:
-
-```bash
-jupyter-repo2docker --debug --no-build https://github.com/jakevdp/PythonDataScienceHandbook
-```
+For more information on how to use ``repo2docker``, see the
+[usage guide](http://repo2docker.readthedocs.io/en/latest/usage.html).
## Repository specifications
-Repo2Docker looks for various files in the repository being built to figure out how to build it.
+Repo2Docker looks for configuration files in the repository being built to figure out how to build it.
It is philosophically similar to [Heroku Build Packs](https://devcenter.heroku.com/articles/buildpacks).
-It currently looks for the following files. They are all composable - you can use any number of them
-in the same repository (except for Dockerfiles, which take precedence over everything else).
-
-### `requirements.txt`
-
-This specifies a list of python packages that would be installed in a virtualenv (or conda environment).
-
-### `environment.yml`
-
-This is a conda environment specification, that lets you install packages with conda. Note that you must
-leave the name of the environment empty for this to work out of the box.
-
-### `apt.txt`
-
-A list of debian packages that should be installed. The base image used is usually the latest released
-version of Ubuntu (currently Zesty.)
-
-### `postBuild`
-
-A script that can contain arbitrary commands to be run after the whole repository has been built. If you
-want this to be a shell script, make sure the first line is `#!/bin/bash`. This file must have the
-executable bit set (`chmod +x postBuild`) to be considered.
-
-### `REQUIRE`
-
-This specifies a list of Julia packages! Currently only version 0.6 of Julia is supported, but more will
-be as they are released.
-
-### `Dockerfile`
-
-This will be treated as a regular Dockerfile and a regular Docker build will be performed. The presence
-of a Dockerfile will cause all other building behavior to not be triggered.
+For a list of the configuration files that ``repo2docker`` can use,
+see the [usage guide](http://repo2docker.readthedocs.io/en/latest/usage.html).
diff --git a/docs/source/faq.md b/docs/source/faq.md
index c97ad3ca..cc0ea916 100644
--- a/docs/source/faq.md
+++ b/docs/source/faq.md
@@ -4,6 +4,11 @@ A collection of frequently asked questions with answers!
If you have a question & have found an answer, send a PR to add it here!
+## How should I specify another version of Python 3?
+
+Currently the best way to do this is by using an ``environment.yaml``
+file and setting the language to whichever version of Python you like.
+
## Can I use repo2docker to bootstrap my own Dockerfile?
No, you can't.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 93f0bb99..9be75157 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -10,6 +10,8 @@ Site Contents
.. toctree::
:maxdepth: 2
+ install
+ usage
design
faq
samples
diff --git a/docs/source/install.rst b/docs/source/install.rst
new file mode 100644
index 00000000..c4b58991
--- /dev/null
+++ b/docs/source/install.rst
@@ -0,0 +1,22 @@
+.. _install:
+
+Installing ``repo2docker``
+==========================
+
+Installing ``repo2docker`` is easiest using the python
+packaging index. In addition, you need to install
+`Docker `_ as it is required in
+order to build images.
+
+To install ``repo2docker`` from pypi, the python packaging index::
+
+ pip install jupyter-repo2docker
+
+To install from source and start contributing::
+
+ git clone https://github.com/jupyter/repo2docker.git
+ cd repo2docker
+ pip install -e .
+
+That's it! For information on using ``repo2docker``, see
+:ref:`usage`.
diff --git a/docs/source/samples.rst b/docs/source/samples.rst
index 367ef044..ad86543a 100644
--- a/docs/source/samples.rst
+++ b/docs/source/samples.rst
@@ -1,5 +1,7 @@
-Sample build files
-==================
+.. _samples:
+
+Sample build repositories
+=========================
There are many options for specifying your environment with ``repo2docker``.
The following sections describe a few samples to get you started.
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
new file mode 100644
index 00000000..708eccac
--- /dev/null
+++ b/docs/source/usage.rst
@@ -0,0 +1,164 @@
+.. _usage:
+
+Using ``repo2docker``
+=====================
+
+The core feature of repo2docker is to fetch a repo (from github or locally),
+build a container image based on the specifications found in the
+repo & optionally launch a local Jupyter Notebook you can use to explore it.
+
+This section describes the general ways in which you can use
+``repo2docker``. It covers basics in how to prepare your
+repository for building, as well as how to use ``repo2docker``
+to build repositories on your own.
+
+See the `Frequently Asked Questions `_ for more info.
+
+Preparing your repository
+-------------------------
+
+``repo2docker`` looks for configuration files in the repository being built
+to determine how to build it. It is philosophically similar to
+`Heroku Build Packs `_.
+``repo2docker`` will look for files in two places:
+
+* The root of the repository.
+* A folder called ``binder`` in the root of the repository (if this folder
+ exists, configuration files in the root of the repository will be ignored).
+
+.. note::
+
+ In general, ``repo2docker`` uses configuration files that are already part of
+ various data science workflows (e.g., ``requirements.txt``), rather than
+ creating new custom configuration files.
+
+``repodocker`` configuration files are all composable - you can use any number
+of them in the same repository, with a few notable exceptions:
+
+* ``Dockerfile``: if a Dockerfile is present in a repository, it will take precedence
+ over all other configuration files (which will be ignored).
+* ``environment.yaml`` with ``requirements.txt``: If both of these files are
+ present, then ``environment.yaml`` will be used to build the image, **not**
+ ``requirements.txt``. If you wish to ``pip install`` packages using an
+ ``environment.yaml`` file, `you should do so with the
+ *pip:* key `_.
+
+ .. note::
+
+ For a list of sample repositories, see :ref:`samples`.
+
+Supported configuration files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Below is a list of supported configuration files.
+
+``requirements.txt``
+^^^^^^^^^^^^^^^^^^^^
+
+This specifies a list of python packages that would be installed in a virtualenv (or conda environment).
+
+``environment.yml``
+^^^^^^^^^^^^^^^^^^^
+
+This is a conda environment specification, that lets you install packages with conda.
+
+.. note::
+
+ You must leave the name of the environment empty for this to work out of the box.
+
+``apt.txt``
+^^^^^^^^^^^
+
+A list of debian packages that should be installed. The base image used is usually the latest released
+version of Ubuntu (currently Zesty.)
+
+``postBuild``
+^^^^^^^^^^^^^
+
+A script that can contain arbitrary commands to be run after the whole repository has been built. If you
+want this to be a shell script, make sure the first line is `#!/bin/bash`.
+
+.. note::
+
+ This file must be executable to be used with ``repo2docker``. To do this,
+ run the following::
+
+ chmod +x postBuild
+
+``REQUIRE``
+^^^^^^^^^^^
+
+This specifies a list of Julia packages! Currently only version 0.6 of Julia is supported, but more will
+be as they are released.
+
+.. note::
+
+ Using a ``REQUIRE`` file also requires that the repository contain an
+ ``environment.yaml`` file.
+
+``Dockerfile``
+^^^^^^^^^^^^^^
+
+This will be treated as a regular Dockerfile and a regular Docker build will be performed. The presence
+of a Dockerfile will cause all other building behavior to not be triggered.
+
+Using ``repo2docker`` with a JupyterHub
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is possible to use ``repo2docker`` in order to build JupyterHub-ready
+Docker images. In order for this to work properly, **the version of the ``jupyterhub``
+package in your git repository must match the version in your JupyterHub
+deployment**. For example, if your JupyterHub deployment runs ``jupyterhub==0.8``,
+you should put the following in ``requirements.txt`` or ``environment.yaml``::
+
+ jupyterhub==0.8.*
+
+Running ``repo2docker`` locally
+-------------------------------
+
+For information on installing ``repo2docker``, see :ref:`install`.
+
+.. note::
+
+ Docker must be running on your machine in order to build images
+ with ``repo2docker``.
+
+Building an image
+~~~~~~~~~~~~~~~~~
+
+The simplest invocation of ``repo2docker`` builds a Docker image
+from a git repo, then runs a Jupyter server within the image
+so you can explore the repository's contents.
+You can do this with the following command::
+
+ jupyter-repo2docker https://github.com/jakevdp/PythonDataScienceHandbook
+
+After building (it might take a while!), it should output in your terminal
+something like::
+
+ Copy/paste this URL into your browser when you connect for the first time,
+ to login with a token:
+ http://0.0.0.0:36511/?token=f94f8fabb92e22f5bfab116c382b4707fc2cade56ad1ace0
+
+If you copy paste that URL into your browser you will see a Jupyter Notebook with the
+contents of the repository you have just built!
+
+Displaying the image Dockerfile
+-------------------------------
+
+``repo2docker`` will generate a Dockerfile that composes the created Docker image.
+To see the contents of this Dockerfile without building the image use
+the ``--debug`` and ``--no-build`` flags like so::
+
+ jupyter-repo2docker --debug --no-build https://github.com/jakevdp/PythonDataScienceHandbook
+
+This will output the contents of the Dockerfile in your console. Note that it
+will **not** build the image.
+
+Other build configurations
+--------------------------
+
+For a list of all the build configurations at your disposal, see the
+CLI help::
+
+ jupyter-repo2docker -h