addressing carol's comments

README.md

@@ -4,7 +4,8 @@
 [![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** takes as input a repository source, such as a GitHub repo. It then builds, runs, and/or pushes Docker images built from
+that source.
 
 See the [repo2docker documentation](http://repo2docker.readthedocs.io)
 for more information.
@@ -62,7 +63,8 @@ For more information on how to use ``repo2docker``, see the
 
 ## Repository specifications
 
-Repo2Docker looks for configuration files in the repository being built to figure out how to build it.
+Repo2Docker looks for configuration files in the source repository to
+determine how the Docker image should be built.
 It is philosophically similar to [Heroku Build Packs](https://devcenter.heroku.com/articles/buildpacks).
 
 For a list of the configuration files that ``repo2docker`` can use,

docs/source/faq.md

@@ -6,7 +6,7 @@ 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``
+Currently the best way to do this is by using a conda ``environment.yml``
 file and setting the language to whichever version of Python you like.
 
 ## Can I use repo2docker to bootstrap my own Dockerfile?

docs/source/install.rst

@@ -3,16 +3,19 @@
 Installing ``repo2docker``
 ==========================
 
-Installing ``repo2docker`` is easiest using the python
-packaging index. In addition, you need to install
-`Docker <https://www.docker.com/>`_ as it is required in
-order to build images.
+1. Install `Docker <https://www.docker.com>`_ as it is required to build Docker images.
 
-To install ``repo2docker`` from pypi, the python packaging index::
+2. We recommend installing ``repo2docker`` with the ``pip`` tool::
 
-  pip install jupyter-repo2docker
+    python3 -m pip install jupyter-repo2docker
 
-To install from source and start contributing::
+For infomation on using ``repo2docker``, see :ref:`usage`.
+
+Installing repo2docker from source code
+---------------------------------------
+
+Alternatively, you can install repo2docker from source,
+i.e. if you are contributing back to this project::
 
   git clone https://github.com/jupyter/repo2docker.git
   cd repo2docker

docs/source/usage.rst

@@ -3,16 +3,20 @@
 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.
+The core functionality of repo2docker is to fetch a repo (e.g., from GitHub or
+other locations) and build a container image based on the specifications found in the
+repo. Optionally, it can launch a local Jupyter Notebook which 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.
+``repo2docker``, including:
 
-See the `Frequently Asked Questions <faq.html>`_ for more info.
+.. contents::
+   :depth: 1
+   :local:
+
+.. note::
+
+   See the `Frequently Asked Questions <faq.html>`_ for more info.
 
 Preparing your repository
 -------------------------
@@ -22,9 +26,9 @@ to determine how to build it. It is philosophically similar to
 `Heroku Build Packs <https://devcenter.heroku.com/articles/buildpacks>`_.
 ``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).
+* A folder called ``binder`` in the root of the repository.
+* The root of the repository. (if a folder called ``binder`` exists in the root
+  of the repository, configuration files outside of that folder will be ignored)
 
 .. note::
 
@@ -33,19 +37,20 @@ to determine how to build it. It is philosophically similar to
    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:
+of them in the same repository. There are a few notable rules:
 
 * ``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**
+* ``environment.yml`` with ``requirements.txt``: If both of these files are
+  present, then ``environment.yml`` 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
+  ``environment.yml`` file, `you should do so with the
   *pip:* key <https://conda.io/docs/user-guide/tasks/manage-environments.html#creating-an-environment-file-manually>`_.
 
   .. note::
 
-     For a list of sample repositories, see :ref:`samples`.
+     For a list of repositories demonstrating various configurations,
+     see :ref:`samples`.
 
 Supported configuration files
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -62,9 +67,10 @@ This specifies a list of python packages that would be installed in a virtualenv
 
 This is a conda environment specification, that lets you install packages with conda.
 
-.. note::
+.. important::
 
-   You must leave the name of the environment empty for this to work out of the box.
+   You must leave the ``environment.yml``'s name field empty for this
+   to work out of the box.
 
 ``apt.txt``
 ^^^^^^^^^^^
@@ -88,13 +94,12 @@ want this to be a shell script, make sure the first line is `#!/bin/bash`.
 ``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.
+This specifies a list of Julia packages!
 
 .. note::
 
    Using a ``REQUIRE`` file also requires that the repository contain an
-   ``environment.yaml`` file.
+   ``environment.yml`` file.
 
 ``Dockerfile``
 ^^^^^^^^^^^^^^
@@ -109,7 +114,7 @@ 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``::
+you should put the following in ``requirements.txt`` or ``environment.yml``::
 
   jupyterhub==0.8.*
 
@@ -133,14 +138,13 @@ 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::
+After building (it might take a while!), it should output a message in your terminal::
 
   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
+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
@@ -155,8 +159,8 @@ the ``--debug`` and ``--no-build`` flags like so::
 This will output the contents of the Dockerfile in your console. Note that it
 will **not** build the image.
 
-Other build configurations
---------------------------
+Accessing help from the command line
+------------------------------------
 
 For a list of all the build configurations at your disposal, see the
 CLI help::