Edit and revision of overview & quick start doc

Signed-off-by: Fred Lifton <[email protected]>

docs/index.md

@@ -1,22 +1,24 @@
----
-layout: default
-title: Compose: Multi-container orchestration for Docker
 page_title: Compose: Multi-container orchestration for Docker
-page_description: Compose: Multi-container orchestration for Docker
-page_keywords: fig, composition, compose, docker
----
+page_description: Introduction and Overview of Compose
+page_keywords: documentation, docs,  docker, compose, orchestration, containers 
 
-# <strong class="strapline">Fast, isolated development environments using Docker.</strong>
 
-Define your app's environment with a `Dockerfile` so it can be reproduced anywhere:
+## Overview
+
+Compose is a tool that allows you to orchestrate multiple Docker containers. With Compose, you can build clusters of containers which provide the resources (services, volumes, etc.) needed to build and run a complete distributed application. 
+
+You can use Compose to build your app with containers hosted locally, or on a remote server, including cloud-based instances. Compose can also be used to deploy code to production.
+
+Using Compose is basically a three-step process.
+ 
+First, you define your app's environment with a `Dockerfile` so it can be reproduced anywhere:
 
     FROM python:2.7
     ADD . /code
     WORKDIR /code
     RUN pip install -r requirements.txt
 
-Define the services that make up your app in `docker-compose.yml` so they can be
-run together in an isolated environment:
+Next, you define the services that make up your app in `docker-compose.yml` so they can be run together in an isolated environment:
 
 ```yaml
 web:
@@ -32,24 +34,25 @@ db:
 
 (No more installing Postgres on your laptop!)
 
-Then type `docker-compose up`, and Compose will start and run your entire app.
+Lastly, run `docker-compose up` and Compose will start and run your entire app.
 
-There are commands to:
+Compose includes commands to:
 
- - start, stop and rebuild services
- - view the status of running services
- - tail running services' log output
- - run a one-off command on a service
+ * Start, stop and rebuild services
+ * View the status of running services
+ * tail the log output of running services
+ * run a one-off command on a service
 
 
 ## Quick start
 
-Let's get a basic Python web app running on Compose. It assumes a little knowledge
-of Python, but the concepts should be clear if you're not familiar with it.
+Let's get started with a walkthrough of getting a simple Python web app running on Compose. It assumes a little knowledge of Python, but the concepts demonstrated here should be understandable even if you're not familiar with Python.
+
+### Installation and set-up
 
 First, [install Docker and Compose](install.html).
 
-You'll want to make a directory for the project:
+Next, you'll want to make a directory for the project:
 
     $ mkdir composetest
     $ cd composetest
@@ -73,25 +76,29 @@ if __name__ == "__main__":
     app.run(host="0.0.0.0", debug=True)
 ```
 
-We define our Python dependencies in a file called `requirements.txt`:
+Next, define the Python dependencies in a file called `requirements.txt`:
 
     flask
     redis
 
-Next, we want to create a Docker image containing all of our app's dependencies.
-We specify how to build one using a file called `Dockerfile`:
+### Create a Docker image
+
+Now, create a Docker image containing all of your app's dependencies. You
+specify how to build the image using a file called [`Dockerfile`](http://docs.docker.com/reference/builder/):
 
     FROM python:2.7
     ADD . /code
     WORKDIR /code
     RUN pip install -r requirements.txt
 
-This tells Docker to install Python, our code and our Python dependencies inside
+This tells Docker to include Python, your code, and your Python dependencies in
 a Docker image. For more information on how to write Dockerfiles, see the
-[Docker user guide](https://docs.docker.com/userguide/dockerimages/#building-an-image-from-a-dockerfile)
-and the [Dockerfile reference](http://docs.docker.com/reference/builder/).
+[Docker user guide](https://docs.docker.com/userguide/dockerimages/#building-an-image-from-a-dockerfile) and the
+[Dockerfile reference](http://docs.docker.com/reference/builder/).
+
+### Define services
 
-We then define a set of services using `docker-compose.yml`:
+Next, define a set of services using `docker-compose.yml`:
 
     web:
       build: .
@@ -107,14 +114,18 @@ We then define a set of services using `docker-compose.yml`:
 
 This defines two services:
 
- - `web`, which is built from `Dockerfile` in the current directory. It also says
-   to run the command `python app.py` inside the image, forward the exposed port
-   5000 on the container to port 5000 on the host machine, connect up the Redis
-   service, and mount the current directory inside the container so we can work
-   on code without having to rebuild the image.
- - `redis`, which uses the public image [redis](https://registry.hub.docker.com/_/redis/). 
+ - `web`, which is built from the `Dockerfile` in the current directory. It also
+ says to run the command `python app.py` inside the image, forward the exposed
+port 5000 on the container to port 5000 on the host machine, connect up the
+Redis service, and mount the current directory inside the container so we can
+work on code without having to rebuild the image.
+ - `redis`, which uses the public image [redis](https://registry.hub.docker.com/_/redis/), which gets pulled from the
+ Docker Hub registry. 
 
-Now if we run `docker-compose up`, it'll pull a Redis image, build an image for our own code, and start everything up:
+### Build and run your app with Compose
+
+Now, when you run `docker-compose up`, Compose will pull a Redis image, build an
+image for your code, and start everything up:
 
     $ docker-compose up
     Pulling image redis...
@@ -124,11 +135,12 @@ Now if we run `docker-compose up`, it'll pull a Redis image, build an image for
     redis_1 | [8] 02 Jan 18:43:35.576 # Server started, Redis version 2.8.3
     web_1   |  * Running on http://0.0.0.0:5000/
 
-The web app should now be listening on port 5000 on your docker daemon (if you're
-using boot2docker, `boot2docker ip` will tell you its address).
+The web app should now be listening on port 5000 on your docker daemon (if
+you're using boot2docker, `boot2docker ip` will tell you its address).
 
-If you want to run your services in the background, you can pass the `-d` flag to
-`docker-compose up` and use `docker-compose ps` to see what is currently running:
+If you want to run your services in the background, you can pass the `-d` flag
+(for daemon mode) to `docker-compose up` and use `docker-compose ps` to see what
+is currently running:
 
     $ docker-compose up -d
     Starting composetest_redis_1...
@@ -139,19 +151,17 @@ If you want to run your services in the background, you can pass the `-d` flag t
     composetest_redis_1   /usr/local/bin/run         Up
     composetest_web_1     /bin/sh -c python app.py   Up      5000->5000/tcp
 
-`docker-compose run` allows you to run one-off commands for your services. For
-example, to see what environment variables are available to the `web` service:
+The `docker-compose run` command allows you to run one-off commands for your
+services. For example, to see what environment variables are available to the
+`web` service:
 
     $ docker-compose run web env
 
-
-See `docker-compose --help` other commands that are available.
+See `docker-compose --help` to see other available commands.
 
 If you started Compose with `docker-compose up -d`, you'll probably want to stop
 your services once you've finished with them:
 
     $ docker-compose stop
 
-That's more-or-less how Compose works. See the reference section below for full
-details on the commands, configuration file and environment variables. If you
-have any thoughts or suggestions, [open an issue on GitHub](https://github.com/docker/docker-compose).
+At this point, you have seen the basics of how Compose works. See the reference section for complete details on the commands, configuration file and environment variables.