diff --git a/README.md b/README.md
index c91370cdf..3ef299bfd 100644
--- a/README.md
+++ b/README.md
@@ -3,15 +3,17 @@ Plum
 
 **WARNING**: This is a work in progress and probably won't work yet. Feedback welcome.
 
-Plum is tool for defining and running apps with Docker. It uses a simple, version-controllable YAML configuration file that looks something like this:
+Plum is tool for defining and running application environments with Docker. It uses a simple, version-controllable YAML configuration file that looks something like this:
 
 ```yaml
+web:
+  build: .
+  links:
+   - db
+  ports:
+   - 8000:8000
 db:
   image: orchardup/postgresql
-
-web:
-  build: web/
-  link: db
 ```
 
 Installing
@@ -26,26 +28,20 @@ Defining your app
 
 Put a `plum.yml` in your app's directory. Each top-level key defines a "service", such as a web app, database or cache. For each service, Plum will start a Docker container, so at minimum it needs to know what image to use.
 
-The way to get started is to just give it an image name:
+The simplest way to get started is to just give it an image name:
 
 ```yaml
 db:
   image: orchardup/postgresql
 ```
 
-Alternatively, you can give it the location of a directory with a Dockerfile (or a Git URL, as per the `docker build` command), and it'll automatically build the image for you:
-
-```yaml
-db:
-  build: /path/to/postgresql/build/directory
-```
-
 You've now given Plum the minimal amount of configuration it needs to run:
 
 ```bash
 $ plum start
-Building db... done
-db is running at 127.0.0.1:45678
+Pulling image orchardup/postgresql...
+Starting myapp_db_1...
+myapp_db_1 is running at 127.0.0.1:45678
 <...output from postgresql server...>
 ```
 
@@ -55,79 +51,99 @@ By default, `plum start` will run until each container has shut down, and relay
 
 ```bash
 $ plum start -d
-Building db... done
-db is running at 127.0.0.1:45678
+Starting myapp_db_1... done
+myapp_db_1 is running at 127.0.0.1:45678
 
 $ plum ps
-SERVICE  STATE  PORT
-db       up     45678
+Name         State  Ports
+------------------------------------
+myapp_db_1   Up     5432->45678/tcp
 ```
 
+### Building services
+
+Plum can automatically build images for you if your service specifies a directory with a `Dockerfile` in it (or a Git URL, as per the `docker build` command).
+
+This example will build an image with `app.py` inside it:
+
+#### app.py
+
+```python
+print "Hello world!"
+```
+
+#### plum.yaml
+
+```yaml
+web:
+  build: .
+```
+
+#### Dockerfile
+
+    FROM ubuntu:12.04
+    RUN apt-get install python
+    ADD . /opt
+    WORKDIR /opt
+    CMD python app.py
+
+
 
 ### Getting your code in
 
-Some services may include your own code. To get that code into the container, ADD it in a Dockerfile.
-
-`plum.yml`:
+If you want to work on an application being run by Plum, you probably don't want to have to rebuild your image every time you make a change. To solve this, you can share the directory with the container using a volume so the changes are reflected immediately:
 
 ```yaml
 web:
-  build: web/
+  build: .
+  volumes:
+   - .:/opt
 ```
 
-`web/Dockerfile`:
-
-    FROM orchardup/rails
-    ADD . /code
-    CMD bundle exec rackup
-
 
 ### Communicating between containers
 
-Your web app will probably need to talk to your database. You can use [Docker links] to enable containers to communicate, pass in the right IP address and port via environment variables:
+Your dweb app will probably need to talk to your database. You can use [Docker links](http://docs.docker.io/en/latest/use/port_redirection/#linking-a-container) to enable containers to communicate, pass in the right IP address and port via environment variables:
 
 ```yaml
 db:
   image: orchardup/postgresql
 
 web:
-  build: web/
-  link: db
+  build: .
+  links:
+   - db
 ```
 
-This will pass an environment variable called DB_PORT into the web container, whose value will look like `tcp://172.17.0.4:45678`. Your web app's code can then use that to connect to the database.
+This will pass an environment variable called `MYAPP_DB_1_PORT` into the web container, whose value will look like `tcp://172.17.0.4:45678`. Your web app's code can use that to connect to the database. To see all of the environment variables available, run `env` inside a container:
 
-You can pass in multiple links, too:
-
-```yaml
-link:
- - db
- - memcached
- - redis
+```bash
+$ plum start -d db
+$ plum run web env
 ```
 
 
-In each case, the resulting environment variable will begin with the uppercased name of the linked service (`DB_PORT`, `MEMCACHED_PORT`, `REDIS_PORT`).
-
-
 ### Container configuration options
 
 You can pass extra configuration options to a container, much like with `docker run`:
 
 ```yaml
 web:
-  build: web/
+  build: .
 
-  -- override the default run command
-  run: bundle exec thin -p 3000
+  -- override the default command
+  command: bundle exec thin -p 3000
 
-  -- expose ports - can also be an array
-  ports: 3000
+  -- expose ports, optionally specifying both host and container ports (a random host port will be chosen otherwise)
+  ports:
+   - 3000
+   - 8000:8000
 
-  -- map volumes - can also be an array
-  volumes: /tmp/cache
+  -- map volumes
+  volumes:
+   - cache/:/tmp/cache
 
-  -- add environment variables - can also be a dictionary
+  -- add environment variables
   environment:
    RACK_ENV: development
 ```
@@ -145,18 +161,3 @@ $ plum run web bash
 ```
 
 
-Running more than one container for a service
----------------------------------------------
-
-You can set the number of containers to run for each service with `plum scale`:
-
-```bash
-$ plum start -d
-db is running at 127.0.0.1:45678
-web is running at 127.0.0.1:45679
-
-$ plum scale db=0,web=3
-Stopped db (127.0.0.1:45678)
-Started web (127.0.0.1:45680)
-Started web (127.0.0.1:45681)
-```