Edits and revisions to Compose Quickstart guides

docs/django.md

@@ -1,14 +1,23 @@
----
-layout: default
-title: Getting started with Compose and Django
----
+page_title: Quickstart Guide: Compose and Django
+page_description: Getting started with Docker Compose and Django
+page_keywords: documentation, docs,  docker, compose, orchestration, containers,
+django
 
-Getting started with Compose and Django
-===================================
 
-Let's use Compose to set up and run a Django/PostgreSQL app. Before starting, you'll need to have [Compose installed](install.md).
+## Getting started with Compose and Django
 
-Let's set up the three files that'll get us started. First, our app is going to be running inside a Docker container which contains all of its dependencies. We can define what goes inside that Docker container using a file called `Dockerfile`. It'll contain this to start with:
+
+This Quick-start Guide will demonstrate how to use Compose to set up and run a
+simple Django/PostgreSQL app. Before starting, you'll need to have
+[Compose installed](install.md).
+
+### Define the project
+
+Start by setting up the three files you'll need to build the app. First, since
+your app is going to run inside a Docker container containing all of its
+dependencies, you'll need to define exactly what needs to be included in the
+container. This is done using a file called `Dockerfile`. To begin with, the
+Dockerfile consists of:
 
     FROM python:2.7
     ENV PYTHONUNBUFFERED 1
@@ -18,14 +27,21 @@ Let's set up the three files that'll get us started. First, our app is going to
     RUN pip install -r requirements.txt
     ADD . /code/
 
-That'll install our application inside an image with Python installed alongside all of our Python dependencies. 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/).
+This Dockerfile will define an image that is used to build a container that
+includes your application and has Python installed alongside all of your Python
+dependencies. 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/).
 
-Second, we define our Python dependencies in a file called `requirements.txt`:
+Second, you'll define your Python dependencies in a file called
+`requirements.txt`:
 
     Django
     psycopg2
 
-Simple enough. Finally, this is all tied together with a file called `docker-compose.yml`. It describes the services that our app comprises of (a web server and database), what Docker images they use, how they link together, what volumes will be mounted inside the containers and what ports they expose.
+Finally, this is all tied together with a file called `docker-compose.yml`. It
+describes the services that comprise your app (here, a web server and database),
+which Docker images they use, how they link together, what volumes will be
+mounted inside the containers, and what ports they expose.
 
     db:
       image: postgres
@@ -39,20 +55,28 @@ Simple enough. Finally, this is all tied together with a file called `docker-com
       links:
         - db
 
-See the [`docker-compose.yml` reference](yml.html) for more information on how it works.
+See the [`docker-compose.yml` reference](yml.html) for more information on how
+this file works.
 
-We can now start a Django project using `docker-compose run`:
+### Build the project
+
+You can now start a Django project with `docker-compose run`:
 
     $ docker-compose run web django-admin.py startproject composeexample .
 
-First, Compose will build an image for the `web` service using the `Dockerfile`. It will then run `django-admin.py startproject composeexample .` inside a container using that image.
+First, Compose will build an image for the `web` service using the `Dockerfile`.
+It will then run `django-admin.py startproject composeexample .` inside a
+container built using that image.
 
 This will generate a Django app inside the current directory:
 
     $ ls
     Dockerfile       docker-compose.yml          composeexample       manage.py        requirements.txt
 
-First thing we need to do is set up the database connection. Replace the `DATABASES = ...` definition in `composeexample/settings.py` to read:
+### Connect the database
+
+Now you need to set up the database connection. Replace the `DATABASES = ...`
+definition in `composeexample/settings.py` to read:
 
     DATABASES = {
         'default': {
@@ -64,7 +88,9 @@ First thing we need to do is set up the database connection. Replace the `DATABA
         }
     }
 
-These settings are determined by the [postgres](https://registry.hub.docker.com/_/postgres/) Docker image we are using.
+These settings are determined by the
+[postgres](https://registry.hub.docker.com/_/postgres/) Docker image specified
+in the Dockerfile.
 
 Then, run `docker-compose up`:
 
@@ -83,13 +109,15 @@ Then, run `docker-compose up`:
     myapp_web_1 | Starting development server at http://0.0.0.0:8000/
     myapp_web_1 | Quit the server with CONTROL-C.
 
-And your Django app should be running at port 8000 on your docker daemon (if you're using boot2docker, `boot2docker ip` will tell you its address).
+Your Django app should nw be running at port 8000 on your Docker daemon (if
+you're using Boot2docker, `boot2docker ip` will tell you its address).
 
-You can also run management commands with Docker. To set up your database, for example, run `docker-compose up` and in another terminal run:
+You can also run management commands with Docker. To set up your database, for
+example, run `docker-compose up` and in another terminal run:
 
     $ docker-compose run web python manage.py syncdb
 
-## Compose documentation
+## More Compose documentation
 
 - [Installing Compose](install.md)
 - [User guide](index.md)