diff --git a/README.md b/README.md
index 1db803a53..e1a1c6d2b 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,20 @@
-Highly experimental branch that implements the following features:
+# Drone
 
-* Pluggable database backends
-* Pluggable queue
-* Matrix builds
-* Build plugins
-* New Yaml syntax
-* and more ...
+Drone is a Continuous Integration platform built on container technology. Every build is executed inside an ephemeral Docker container, giving developers complete control over their build environment with guaranteed isolation.
+
+## Documentation
+
+Drone documentation is organized into several categories:
+
+* [Setup Guide](http://readme.drone.io/docs/setup/)
+* [Build Guide](http://readme.drone.io/docs/build/)
+* [API Reference](http://readme.drone.io/docs/api/)
+
+## Community
+
+Contributions, questions, and comments are all welcomed and encouraged! Drone developers hang out in the [drone/drone](https://gitter.im/drone/drone) room on [gitter](https://gitter.im/drone/drone).
+
+---
 
 Running Drone:
 
diff --git a/doc/build/build.md b/doc/build/build.md
index 038058bbc..3229b9600 100644
--- a/doc/build/build.md
+++ b/doc/build/build.md
@@ -45,19 +45,6 @@ image: library/golang:1.4
 image: index.docker.io/library/golang:1.4
 ```
 
-## Build environment
-
-The build environment has access to the following environment variables:
-
-* `CI=true`
-* `DRONE=true`
-* `DRONE_REPO` - repository name for the current build
-* `DRONE_BUILD` - build number for the current build
-* `DRONE_BRANCH` - branch name for the current build
-* `DRONE_COMMIT` - git sha for the current build
-* `DRONE_DIR` - working directory for the current build
-
-
 ## Skipping builds
 
 Skip a build by including the text `[CI SKIP]` in your commit message.
diff --git a/doc/build/clone.md b/doc/build/clone.md
index 04d1a6569..c326b615c 100644
--- a/doc/build/clone.md
+++ b/doc/build/clone.md
@@ -31,11 +31,11 @@ git clone --depth=50 --recusive=true \
 
 Cloning a private repository requires authentication to the remote system. Drone prefers `git+https` and `netrc` to authenticate, but will fallback to `git+ssh` and deploy keys if not supported.
 
-Drone prefers `git+ssh` for authentication because it allows you to clone multiple private repositories. This is helpful when you have git submodules or third party dependencies you need to download (via `go get` or `npm install` or others) that are sourced from a private repository.
+Drone prefers `git+https` for authentication because it allows you to clone multiple private repositories. This is helpful when you have git submodules or third party dependencies you need to download (via `go get` or `npm install` or others) that are sourced from a private repository.
 
 Drone only injects the `netrc` and `id_rsa` files into your build environment if your repository is private, or running in private mode. We do this for security reasons to avoid leaking sensitive data.
 
-## Clone Plugins
+## Clone Plugin
 
 You can override the default `git` plugin by specifying an alternative plugin image. An example use case may be integrating with alternate version control systems, such as mercurial:
 
diff --git a/doc/build/deploy.md b/doc/build/deploy.md
index ec237ecad..6b1960015 100644
--- a/doc/build/deploy.md
+++ b/doc/build/deploy.md
@@ -28,46 +28,7 @@ deploy:
       branch: feature/*
 ```
 
-<!--
-## Deploy plugins
-
-Deployment plugins are Docker images that attach to your build environment at runtime. They are declared in the `.drone.yml` using the following format:
-
-```
-deploy:
-  [step_name:]
-    [image:]
-    [options]
-```
-
-An example `heroku` plugin configuration:
-
-```yaml
-deploy:
-  heroku:
-    image: plugins/heroku
-    app: pied_piper
-    token: f10e2821bbbea5
-```
-
-The `image` attribute is optional. If the `image` is not specified Drone attempts to use the `step_name` as the `image` name. The below examples both produce identical output:
-
-```yaml
-  # this step specifies an image
-
-  heroku:
-    image: plubins/heroku
-    app: pied_piper
-    token: f10e2821bbbea5
-
-  # and this step infers the image from the step_name
-
-  heroku:
-    app: pied_piper
-    token: f10e2821bbbea5
-```
-
-The `image` attribute is useful when you need to invoke the same plugin multiple times. For example, we may want to deploy to multiple `heroku` environments depending on branch:
+Use a more verbose `.drone.yml` syntax to declare multiple `heroku` deployment steps:
 
 ```yaml
   # deploy master to our production heroku environment
@@ -83,5 +44,11 @@ The `image` attribute is useful when you need to invoke the same plugin multiple
     image: plugins/heroku
     when:
       branch: stage
+
+  # this is the same as above, but uses a short-hand syntax
+  # and infers the `image` name
+
+  heroku:
+    when:
+      branch: stage
 ```
--->
diff --git a/doc/build/env.md b/doc/build/env.md
index 018ee1d99..704dc103d 100644
--- a/doc/build/env.md
+++ b/doc/build/env.md
@@ -25,7 +25,7 @@ build:
     - go build
     - go test
 
-publish:
+deploy:
   heroku:
     app: pied_piper
     token: $$HEROKU_TOKEN