Flush out features and use cases.

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

README.md

@@ -4,13 +4,15 @@ Docker Compose
 
 *(Previously known as Fig)*
 
-Compose is a tool for defining and running multi-container applications with
+Compose is a tool for defining and running multi-container Docker applications.
-Docker. With Compose, you define a multi-container application in a single
+With Compose, you define a multi-container application in a compose
-file, then spin your application up in a single command which does everything
+file then, using a single command, you create and start all the containers
-that needs to be done to get it running.
+from your configuration. To learn more about all the features of Compose
+see [the list of features](#features)
 
-Compose is great for development environments, staging servers, and CI. We don't
+Compose is great for development, testing, and staging environments, as well as
-recommend that you use it in production yet.
+CI workflows. You can learn more about each case in
+[Common Use Cases](#common-use-cases).
 
 Using Compose is basically a three-step process.
 
@@ -33,6 +35,9 @@ A `docker-compose.yml` looks like this:
     redis:
       image: redis
 
+For more information about the Compose file, see the
+[Compose file reference](docs/yml.md)
+
 Compose has commands for managing the whole lifecycle of your application:
 
  * Start, stop and rebuild services

docs/index.md

@@ -11,20 +11,22 @@ parent="smn_workw_compose"
 
 # Overview of Docker Compose
 
-Compose is a tool for defining and running multi-container applications with
+Compose is a tool for defining and running multi-container Docker applications.
-Docker. With Compose, you define a multi-container application in a single
+With Compose, you define a multi-container application in a compose
-file, then spin your application up in a single command which does everything
+file then, using a single command, you create and start all the containers
-that needs to be done to get it running.
+from your configuration. To learn more about all the features of Compose
+see [the list of features](#features)
 
-Compose is great for development environments, staging servers, and CI. We don't
+Compose is great for development, testing, and staging environments, as well as
-recommend that you use it in production yet.
+CI workflows. You can learn more about each case in
+[Common Use Cases](#common-use-cases).
 
 Using Compose is basically a three-step process.
 
 1. Define your app's environment with a `Dockerfile` so it can be
 reproduced anywhere.
 2. Define the services that make up your app in `docker-compose.yml` so
-they can be run together in an isolated environment:
+they can be run together in an isolated environment.
 3. Lastly, run `docker-compose up` and Compose will start and run your entire app.
 
 A `docker-compose.yml` looks like this:
@@ -40,6 +42,9 @@ A `docker-compose.yml` looks like this:
     redis:
       image: redis
 
+For more information about the Compose file, see the
+[Compose file reference](yml.md)
+
 Compose has commands for managing the whole lifecycle of your application:
 
  * Start, stop and rebuild services
@@ -57,11 +62,84 @@ Compose has commands for managing the whole lifecycle of your application:
 - [Command line reference](./reference/index.md)
 - [Compose file reference](compose-file.md)
 
+## Features
+
+#### Preserve volume data
+
+Compose preserves all volumes used by your services. When `docker-compose up`
+runs, if it finds any containers from previous runs, it copies the volumes from
+the old container to the new container. This process ensures that any data
+you've created in volumes isn't lost.
+
+
+#### Only recreate containers that have changed
+
+Compose caches the configuration used to create a container. When you
+restart a service that has not changed, Compose re-uses the existing
+containers. Re-using containers means that you can make changes to your
+environment very quickly.
+
+
+#### Variables and moving a composition to different 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`
+field in a compose file, or by using multiple files. See [extends](extends.md)
+for more details.
+
+
+## Common Use Cases
+
+Compose can be used in many different ways. Some common use cases are outlined
+below.
+
+### Development environments
+
+When you're developing software it is often helpful to be able to run the
+application and interact with it. If the application has any service dependencies
+(databases, queues, caches, web services, etc) you need a way to document the
+dependencies, configuration and operation of each. Compose provides a convenient
+format for definition these dependencies (the [Compose file](yml.md)) and a CLI
+tool for starting an isolated environment. Compose can replace a multi-page
+"developer getting started guide" with a single machine readable configuration
+file and a single command `docker-compose up`.
+
+### Automated testing environments
+
+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
+environments in just a few commands:
+
+    $ docker-compose up -d
+    $ ./run_tests
+    $ docker-compose stop
+    $ docker-compose rm -f
+
+### Single host deployments
+
+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
+instance provisioned with [Docker Machine](https://docs.docker.com/machine/) or
+a [Docker Swarm](https://docs.docker.com/swarm/) cluster.
+
+See [compose in production](production.md) for more details.
+
 
 ## Release Notes
 
 To see a detailed list of changes for past and current releases of Docker
-Compose, please refer to the [CHANGELOG](https://github.com/docker/compose/blob/master/CHANGELOG.md).
+Compose, please refer to the
+[CHANGELOG](https://github.com/docker/compose/blob/master/CHANGELOG.md).
 
 ## Getting help