Merge pull request #949 from aanand/update-intro

Rejig introduction

README.md

@@ -3,17 +3,30 @@ Docker Compose
 
 [![wercker status](https://app.wercker.com/status/d5dbac3907301c3d5ce735e2d5e95a5b/s/master "wercker status")](https://app.wercker.com/project/bykey/d5dbac3907301c3d5ce735e2d5e95a5b)
 
-Fast, isolated development environments using Docker.
+Compose is a tool for defining and running complex applications with Docker.
+With Compose, you define a multi-container application in a single file, then
+spin your application up in a single command which does everything that needs to
+be done to get it running.
 
-Define your app's environment with Docker so it can be reproduced anywhere:
+Compose is great for development environments, staging servers, and CI. We don't
+recommend that you use it in production yet.
 
-    FROM python:2.7
+Using Compose is basically a three-step process.
-    ADD . /code
-    WORKDIR /code
-    RUN pip install -r requirements.txt
-    CMD python app.py
 
-Define the services that make up your app so they can be run together in an isolated environment:
+First, you define your app's environment with a `Dockerfile` so it can be
+reproduced anywhere:
+
+```Dockerfile
+FROM python:2.7
+WORKDIR /code
+ADD requirements.txt /code/
+RUN pip install -r requirements.txt
+ADD . /code
+CMD python app.py
+```
+
+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:
@@ -22,21 +35,18 @@ web:
    - db
   ports:
    - "8000:8000"
-   - "49100:22"
 db:
   image: postgres
 ```
 
-(No more installing Postgres on your laptop!)
+Lastly, run `docker-compose up` and Compose will start and run your entire app.
 
-Then type `docker-compose up`, and Compose will start and run your entire app.
+Compose has commands for managing the whole lifecycle of your application:
 
-There are commands to:
+ * Start, stop and rebuild services
-
+ * View the status of running services
- - start, stop and rebuild services
+ * Stream the log output of running services
- - view the status of running services
+ * Run a one-off command on a service
- - tail running services' log output
- - run a one-off command on a service
 
 Installation and documentation
 ------------------------------

docs/index.md

@@ -5,26 +5,27 @@ page_keywords: documentation, docs,  docker, compose, orchestration, containers
 
 ## Overview
 
-Compose is a tool that allows you to orchestrate multiple Docker containers.
+Compose is a tool for defining and running complex applications with Docker.
-With Compose, you can build clusters of containers which provide the resources
+With Compose, you define a multi-container application in a single file, then
-(services, volumes, etc.) needed to build and run a complete distributed
+spin your application up in a single command which does everything that needs to
-application.
+be done to get it running.
 
-You can use Compose to build your app with containers hosted locally, or on a
+Compose is great for development environments, staging servers, and CI. We don't
-remote server, including cloud-based instances - anywhere a Docker daemon can
+recommend that you use it in production yet.
-run. Its primary use case is for development environments, but it can be used
-just as easily for staging or CI.
 
 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
+```Dockerfile
-    WORKDIR /code
+FROM python:2.7
-    ADD requirements.txt /code/
+WORKDIR /code
-    RUN pip install -r requirements.txt
+ADD requirements.txt /code/
-    ADD . /code
+RUN pip install -r requirements.txt
+ADD . /code
+CMD python app.py
+```
 
 Next, you define the services that make up your app in `docker-compose.yml` so
 they can be run together in an isolated environment:
@@ -32,7 +33,6 @@ they can be run together in an isolated environment:
 ```yaml
 web:
   build: .
-  command: python app.py
   links:
    - db
   ports:
@@ -41,16 +41,14 @@ db:
   image: postgres
 ```
 
-(No more installing Postgres on your laptop!)
-
 Lastly, run `docker-compose up` and Compose will start and run your entire app.
 
-Compose includes commands to:
+Compose has commands for managing the whole lifecycle of your application:
 
  * Start, stop and rebuild services
  * View the status of running services
- * tail the log output of running services
+ * Stream the log output of running services
- * run a one-off command on a service
+ * Run a one-off command on a service
 
 
 ## Quick start