tim comments in specification doc

docs/source/specification.rst

@@ -10,18 +10,20 @@ and the resulting actions that repo2docker takes is known
 as the **Reproducible Execution Environment Specification** (or REES).
 
 The goal of the REES is to automate and encourage existing community best practices
-for reproducible computational environments. This includes installing
+for reproducible computational environments. This includes installing pacakges using
-community-standard specification files such as ``requirements.txt`` or ``REQUIRE`` using
+community-standard specification files and their corresponding tools,
-standard tools such as ``pip`` or ``conda`` or ``apt``. While repo2docker automates the
+such as ``requirements.txt`` (with ``pip``), ``REQUIRE`` (with Julia), or
+``apt.txt`` (with ``apt``). While repo2docker automates the
 creation of the environment, a human should be able to look at a REES-compliant
 repository and reproduce the environment using common, clear steps without
 repo2docker software.
 
 Currently, the definition of the REE Specification is the following:
 
-    Any collection of files taken from the :ref:`config-files`
+    Any directory containing zero or more files from the :ref:`config-files` list is a
-    list, placed either in the root of a folder or in a sub-folder called
+    valid reproducible execution environment as defined by the REES. The
-    either ``binder/`` or ``.binder/``.
+    configuration files have to all be placed either in the root of the
+    directory, in a ``binder/`` sub-directory or a ``.binder/`` sub-directory.
 
 For example, the REES recognises ``requirements.txt`` as a valid config file.
 The file format is as defined by the ``requirements.txt`` standard of the Python

docs/source/usage.rst

@@ -11,7 +11,7 @@ Using ``repo2docker``
    ``repo2docker``, see :ref:`install`.
 
 ``repo2docker`` can build a reproducible computational environment for any repository that
-follows :ref:`specification`. repo2docker is called with a URL/path to a git repository. It then
+follows :ref:`specification`. repo2docker is called with a URL/path to a repository. It then
 performs these steps:
 
 1. Inspects the repository for :ref:`configuration files <config-files>`. These will be used to build