Update intro docs based on feedback.

Signed-off-by: Daniel Nephin <dnephin@docker.com>

README.md

@@ -2,8 +2,6 @@ Docker Compose
 ==============
 ![Docker Compose](logo.png?raw=true "Docker Compose Logo")
 
-*(Previously known as Fig)*
-
 Compose is a tool for defining and running multi-container Docker applications.
 With Compose, you define a multi-container application in a compose
 file then, using a single command, you create and start all the containers
@@ -36,7 +34,7 @@ A `docker-compose.yml` looks like this:
       image: redis
 
 For more information about the Compose file, see the
-[Compose file reference](docs/yml.md)
+[Compose file reference](docs/compose-file.md)
 
 Compose has commands for managing the whole lifecycle of your application:
 

docs/gettingstarted.md

@@ -10,24 +10,28 @@ weight=3
 <![end-metadata]-->
 
 
-## Getting Started
+# Getting Started
 
-Let's get started with a walkthrough of getting a simple Python web app running
+On this page you build a simple Python web application running on Compose. The
-on Compose. It assumes a little knowledge of Python, but the concepts
+application uses the Flask framework and increments a value in Redis. While the
-demonstrated here should be understandable even if you're not familiar with
+sample uses Python, the concepts demonstrated here should be understandable even
-Python.
+if you're not familiar with it.
 
-### Installation and set-up
+## Prerequisites
 
-First, [install Docker and Compose](install.md).
+Make sure you have already
+[installed both Docker Engine and Docker Compose](install.md). You
+don't need to install Python, it is provided by a Docker image.
 
-Create a directory for the project:
+## Step 1: Setup
+
+1. Create a directory for the project:
 
         $ mkdir composetest
         $ cd composetest
 
-Inside this directory, create `app.py`, a simple Python web app that uses the Flask
+2. With your favorite text editor create a file called `app.py` in your project
-framework and increments a value in Redis.
+   directory.
 
         from flask import Flask
         from redis import Redis
@@ -43,16 +47,21 @@ framework and increments a value in Redis.
         if __name__ == "__main__":
             app.run(host="0.0.0.0", debug=True)
 
-Next, define the Python dependencies in a file called `requirements.txt`:
+3. Create another file called `requirements.txt` in your project directory and
+   add the following:
 
         flask
         redis
 
-### Create a Docker image
+   These define the applications dependencies.
 
-Now, create a Docker image containing all of your app's dependencies. You
+## Step 2: Create a Docker image
-specify how to build the image using a file called
+
-[`Dockerfile`](http://docs.docker.com/reference/builder/):
+In this step, you build a new Docker image. The image contains all the
+dependencies the Python application requires, including Python itself.
+
+1. In your project directory create a file named `Dockerfile` and add the
+   following:
 
         FROM python:2.7
         ADD . /code
@@ -70,12 +79,22 @@ This tells Docker to:
 
   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/).
 
-You can build the image by running `docker build -t web .`.
+2. Build the image.
 
-### Define services
+        $ docker build -t web .
+
+  This command builds an image named `web` from the contents of the current
+  directory. The command automatically locates the `Dockerfile`, `app.py`, and
+  `requirements.txt` files.
+
+
+## Step 3: Define services
 
 Define a set of services using `docker-compose.yml`:
 
+1. Create a file called docker-compose.yml in your project directory and add
+   the following:
+
         web:
           build: .
           ports:
@@ -87,7 +106,7 @@ Define a set of services using `docker-compose.yml`:
         redis:
           image: redis
 
-This template defines two services, `web` and `redis`. The `web` service:
+This Compose file defines two services, `web` and `redis`. The web service:
 
 * Builds from the `Dockerfile` in the current directory.
 * Forwards the exposed port 5000 on the container to port 5000 on the host machine.
@@ -96,9 +115,9 @@ This template defines two services, `web` and `redis`. The `web` service:
 
 The `redis` service uses the latest public [Redis](https://registry.hub.docker.com/_/redis/) image pulled from the Docker Hub registry.
 
-### Build and run your app with Compose
+## Step 4: 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:
+1. From your project directory, start up your application.
 
         $ docker-compose up
         Pulling image redis...
@@ -109,15 +128,28 @@ Now, when you run `docker-compose up`, Compose will pull a Redis image, build an
         web_1   |  * Running on http://0.0.0.0:5000/
         web_1   |  * Restarting with stat
 
-If you're using [Docker Machine](https://docs.docker.com/machine), then `docker-machine ip MACHINE_VM` will tell you its address and you can open `http://MACHINE_VM_IP:5000` in a browser.
+   Compose pulls a Redis image, builds an image for your code, and start the
+   services you defined.
 
-If you're using Docker on Linux natively, then the web app should now be listening on port 5000 on your Docker daemon host. If `http://0.0.0.0:5000` doesn't resolve, you can also try `http://localhost:5000`.
+2. Enter `http://0.0.0.0:5000/` in a browser to see the application running.
 
-You will see a message in your browser saying:
+   If you're using Docker on Linux natively, then the web app should now be
+   listening on port 5000 on your Docker daemon host. If http://0.0.0.0:5000
+   doesn't resolve, you can also try http://localhost:5000.
+
+   If you're using Docker Machine on a Mac, use `docker-machine ip MACHINE_VM` to get
+   the IP address of your Docker host. Then, `open http://MACHINE_VM_IP:5000` in a
+   browser.
+
+   You should see a message in your browser saying:
 
    `Hello World! I have been seen 1 times.`
 
-Refreshing the page will increment the number.
+3. Refresh the page.
+
+   The number should increment.
+
+## Step 5: Experiment with some other commands
 
 If you want to run your services in the background, you can pass the `-d` flag
 (for "detached" mode) to `docker-compose up` and use `docker-compose ps` to
@@ -147,17 +179,10 @@ your services once you've finished with them:
 
 At this point, you have seen the basics of how Compose works.
 
+
+## Where to go next
+
 - Next, try the quick start guide for [Django](django.md),
   [Rails](rails.md), or [WordPress](wordpress.md).
-- See the reference guides for complete details on the [commands](./reference/index.md), the
+- [Explore the full list of Compose commands](./reference/index.md)
-  [configuration file](compose-file.md) and [environment variables](env.md).
+- [Compose configuration file reference](compose-file.md)
-
-## More Compose documentation
-
-- [User guide](/)
-- [Installing Compose](install.md)
-- [Get started with Django](django.md)
-- [Get started with Rails](rails.md)
-- [Get started with WordPress](wordpress.md)
-- [Command line reference](./reference/index.md)
-- [Compose file reference](compose-file.md)

docs/index.md

@@ -43,7 +43,7 @@ A `docker-compose.yml` looks like this:
       image: redis
 
 For more information about the Compose file, see the
-[Compose file reference](yml.md)
+[Compose file reference](compose-file.md)
 
 Compose has commands for managing the whole lifecycle of your application:
 
@@ -64,6 +64,12 @@ Compose has commands for managing the whole lifecycle of your application:
 
 ## Features
 
+The features of Compose that make it effective are:
+
+* [Preserve volume data](#preserve-volume-data)
+* [Only recreate containers that have changed](#only-recreate-containers-that-have-changed)
+* [Variables and moving a composition between environments](#variables-and-moving-a-composition-between-environments)
+
 #### Preserve volume data
 
 Compose preserves all volumes used by your services. When `docker-compose up`
@@ -80,18 +86,15 @@ containers. Re-using containers means that you can make changes to your
 environment very quickly.
 
 
-#### Variables and moving a composition to different environments
+#### Variables and moving a composition between environments
-
-> New in `docker-compose` 1.5
 
 Compose supports variables in the Compose file. You can use these variables
 to customize your composition for different environments, or different users.
 See [Variable substitution](compose-file.md#variable-substitution) for more
 details.
 
-Compose files can also be extended from other files using the `extends`
+You can extend a Compose file using the `extends` field or by creating multiple
-field in a compose file, or by using multiple files. See [extends](extends.md)
+Compose files. See [extends](extends.md) for more details.
-for more details.
 
 
 ## Common Use Cases
@@ -101,14 +104,19 @@ below.
 
 ### Development environments
 
-When you're developing software it is often helpful to be able to run the
+When you're developing software, the ability to run an application in an
-application and interact with it. If the application has any service dependencies
+isolated environment and interact with it is crucial.  The Compose command
-(databases, queues, caches, web services, etc) you need a way to document the
+line tool can be used to create the environment and interact with it.
-dependencies, configuration and operation of each. Compose provides a convenient
+
-format for definition these dependencies (the [Compose file](yml.md)) and a CLI
+The [Compose file](compose-file.md) provides a way to document and configure
-tool for starting an isolated environment. Compose can replace a multi-page
+all of the application's service dependencies (databases, queues, caches,
-"developer getting started guide" with a single machine readable configuration
+web service APIs, etc). Using the Compose command line tool you can create
-file and a single command `docker-compose up`.
+and start one or more containers for each dependency with a single command
+(`docker-compose up`).
+
+Together, these features provide a convenient way for developers to get
+started on a project.  Compose can reduce a multi-page "developer getting
+started guide" to a single machine readable Compose file and a few commands.
 
 ### Automated testing environments
 
@@ -116,7 +124,7 @@ An important part of any Continuous Deployment or Continuous Integration process
 is the automated test suite. Automated end-to-end testing requires an
 environment in which to run tests. Compose provides a convenient way to create
 and destroy isolated testing environments for your test suite. By defining the full
-environment in a [Compose file](yml.md) you can create and destroy these
+environment in a [Compose file](compose-file.md) you can create and destroy these
 environments in just a few commands:
 
     $ docker-compose up -d
@@ -128,11 +136,13 @@ environments in just a few commands:
 
 Compose has traditionally been focused on development and testing workflows,
 but with each release we're making progress on more production-oriented features.
-Compose can be used to deploy to a remote docker engine, for example a cloud
+You can use Compose to deploy to a remote Docker Engine. The Docker Engine may
-instance provisioned with [Docker Machine](https://docs.docker.com/machine/) or
+be a single instance provisioned with
-a [Docker Swarm](https://docs.docker.com/swarm/) cluster.
+[Docker Machine](https://docs.docker.com/machine/) or an entire
+[Docker Swarm](https://docs.docker.com/swarm/) cluster.
 
-See [compose in production](production.md) for more details.
+For details on using production-oriented features, see
+[compose in production](production.md) in this documentation.
 
 
 ## Release Notes