diff --git a/docs/design/simple-rolling-update.md b/docs/design/simple-rolling-update.md
index 43b086ae8a9..2d2bd8265f5 100644
--- a/docs/design/simple-rolling-update.md
+++ b/docs/design/simple-rolling-update.md
@@ -57,7 +57,6 @@ then ```foo-next``` is synthesized using the pattern ```<controller-name>-<hash-
 #### Initialization
    * If ```foo``` and ```foo-next``` do not exist:
       * Exit, and indicate an error to the user, that the specified controller doesn't exist.
-      * Goto Rollout
    * If ```foo``` exists, but ```foo-next``` does not:
       * Create ```foo-next``` populate it with the ```v2``` image, set ```desired-replicas``` to ```foo.Spec.Replicas```
       * Goto Rollout
diff --git a/docs/getting-started-guides/aws.md b/docs/getting-started-guides/aws.md
index 2e1cb10655b..a87ef0aa094 100644
--- a/docs/getting-started-guides/aws.md
+++ b/docs/getting-started-guides/aws.md
@@ -32,97 +32,21 @@ Once the cluster is up, it will print the ip address of your cluster, this proce
 export KUBERNETES_MASTER=https://<ip-address>
 ```
 
-Also setup your path to point to the released binaries:
-```
-export PATH=$PATH:$PWD:/kubernetes/cluster
-```
-
-If you run into trouble come ask questions on IRC at #google-containers on freenode.
-
-
-### Running a container (simple version)
-
-Once you have your cluster created you can use ```${SOME_DIR}/kubernetes/cluster/kubectl.sh``` to access
-the kubernetes api.
-
-The `kubectl.sh` line below spins up two containers running
-[Nginx](http://nginx.org/en/) running on port 80:
+Copy the appropriate ```kubectl``` binary to somewhere in your ```PATH```, for example:
 
 ```bash
-cluster/kubectl.sh run-container my-nginx --image=nginx --replicas=2 --port=80
+# OS X
+sudo cp kubernetes/platforms/darwin/amd64/kubectl /usr/local/bin/kubectl
+
+# Linux
+sudo cp kubernetes/platforms/linux/amd64/kubectl /usr/local/bin/kubectl
 ```
 
-To stop the containers:
 
-```bash
-cluster/kubectl.sh stop rc my-nginx
-```
+### Getting started with your cluster
+See [a simple nginx example](../../examples/simple-nginx.md) to try out your new cluster.
 
-To delete the containers:
-
-```bash
-cluster/kubectl.sh delete rc my-nginx
-```
-
-### Running a container (more complete version)
-
-```bash
-cd kubernetes
-cluster/kubectl.sh create -f docs/getting-started-guides/pod.json
-```
-
-Where pod.json contains something like:
-
-```json
-{
-  "id": "php",
-  "kind": "Pod",
-  "apiVersion": "v1beta1",
-  "desiredState": {
-    "manifest": {
-      "version": "v1beta1",
-      "id": "php",
-      "containers": [{
-        "name": "nginx",
-        "image": "nginx",
-        "ports": [{
-          "containerPort": 80,
-          "hostPort": 8081
-        }],
-        "livenessProbe": {
-          "enabled": true,
-          "type": "http",
-          "initialDelaySeconds": 30,
-          "httpGet": {
-            "path": "/index.html",
-            "port": 8081
-          }
-        }
-      }]
-    }
-  },
-  "labels": {
-    "name": "foo"
-  }
-}
-```
-
-You can see your cluster's pods:
-
-```bash
-cluster/kubectl.sh get pods
-```
-
-and delete the pod you just created:
-
-```bash
-cluster/kubectl.sh delete pods php
-```
-
-Since this pod is scheduled on a minion running in AWS, you will have to enable incoming tcp traffic via the port specified in the
-pod manifest before you see the nginx welcome page. After doing so, it should be visible at http://<external ip of minion running nginx>:<port from manifest>.
-
-Look in `examples/` for more examples
+For more complete applications, please look in the [examples directory](../../examples)
 
 ### Tearing down the cluster
 ```bash
diff --git a/docs/getting-started-guides/docker-multinode.md b/docs/getting-started-guides/docker-multinode.md
index c2fe5568aaa..a7f4b02b0cc 100644
--- a/docs/getting-started-guides/docker-multinode.md
+++ b/docs/getting-started-guides/docker-multinode.md
@@ -40,4 +40,6 @@ See [here](docker-multinode/worker.md) for detailed instructions.
 
 ## Testing your cluster
 
-Once your cluster has been created you can [test it out](docker-multinode/testing.md)
\ No newline at end of file
+Once your cluster has been created you can [test it out](docker-multinode/testing.md)
+
+For more complete applications, please look in the [examples directory](../../examples)
diff --git a/docs/getting-started-guides/gce.md b/docs/getting-started-guides/gce.md
index c91aa129f13..22e0167bd85 100644
--- a/docs/getting-started-guides/gce.md
+++ b/docs/getting-started-guides/gce.md
@@ -33,99 +33,24 @@ wget -q -O - https://get.k8s.io | bash
 
 This will leave you with a ```kubernetes``` directory on your workstation, and a running cluster.
 
-Feel free to move the ```kubernetes``` directory to the appropriate directory on your workstation (e.g. ```/opt/kubernetes```) then ```cd``` into that directory:
+Copy the appropriate ```kubectl``` binary to somewhere in your ```PATH```, for example:
 
 ```bash
-mv kubernetes ${SOME_DIR}/kubernetes
-cd ${SOME_DIR}/kubernetes
+# OS X
+sudo cp kubernetes/platforms/darwin/amd64/kubectl /usr/local/bin/kubectl
+
+# Linux
+sudo cp kubernetes/platforms/linux/amd64/kubectl /usr/local/bin/kubectl
 ```
 
 If you run into trouble please see the section on [troubleshooting](https://github.com/brendandburns/kubernetes/blob/docs/docs/getting-started-guides/gce.md#troubleshooting), or come ask questions on IRC at #google-containers on freenode.
 
 
-### Running a container (simple version)
+### Getting started with your cluster
+See [a simple nginx example](../../examples/simple-nginx.md) to try out your new cluster.
 
-Once you have your cluster created you can use ```${SOME_DIR}/kubernetes/cluster/kubectl.sh``` to access
-the kubernetes api.
+For more complete applications, please look in the [examples directory](../../examples)
 
-The `kubectl.sh` line below spins up two containers running
-[Nginx](http://nginx.org/en/) running on port 80:
-
-```bash
-cluster/kubectl.sh run-container my-nginx --image=nginx --replicas=2 --port=80
-```
-
-To stop the containers:
-
-```bash
-cluster/kubectl.sh stop rc my-nginx
-```
-
-To delete the containers:
-
-```bash
-cluster/kubectl.sh delete rc my-nginx
-```
-
-### Running a container (more complete version)
-
-```bash
-cd kubernetes
-cluster/kubectl.sh create -f docs/getting-started-guides/pod.json
-```
-
-Where pod.json contains something like:
-
-```json
-{
-  "id": "php",
-  "kind": "Pod",
-  "apiVersion": "v1beta1",
-  "desiredState": {
-    "manifest": {
-      "version": "v1beta1",
-      "id": "php",
-      "containers": [{
-        "name": "nginx",
-        "image": "nginx",
-        "ports": [{
-          "containerPort": 80,
-          "hostPort": 8081
-        }],
-        "livenessProbe": {
-          "enabled": true,
-          "type": "http",
-          "initialDelaySeconds": 30,
-          "httpGet": {
-            "path": "/index.html",
-            "port": 8081
-          }
-        }
-      }]
-    }
-  },
-  "labels": {
-    "name": "foo"
-  }
-}
-```
-
-You can see your cluster's pods:
-
-```bash
-cluster/kubectl.sh get pods
-```
-
-and delete the pod you just created:
-
-```bash
-cluster/kubectl.sh delete pods php
-```
-
-Since this pod is scheduled on a minion running in GCE, you will have to enable incoming tcp traffic via the port specified in the
-pod manifest before you see the nginx welcome page. After doing so, it should be visible at http://<external ip of minion running nginx>:<port from manifest>.
-
-Look in `examples/` for more examples
 
 ### Tearing down the cluster
 
diff --git a/docs/getting-started-guides/pod.json b/docs/getting-started-guides/pod.json
deleted file mode 100644
index 296fedad862..00000000000
--- a/docs/getting-started-guides/pod.json
+++ /dev/null
@@ -1,32 +0,0 @@
-{
-  "kind": "Pod",
-  "apiVersion": "v1beta1",
-  "id": "php",
-  "desiredState": {
-    "manifest": {
-      "version": "v1beta1",
-      "id": "php",
-      "containers": [{
-        "name": "nginx",
-        "image": "nginx",
-        "ports": [{
-          "containerPort": 80,
-          "hostPort": 8081
-        }],
-        "livenessProbe": {
-          "enabled": true,
-          "type": "http",
-          "initialDelaySeconds": 30,
-          "httpGet": {
-            "path": "/",
-            "port": "80"
-          }
-        }
-      }]
-    }
-  },
-  "labels": {
-    "name": "foo"
-  }
-}
-
diff --git a/examples/examples_test.go b/examples/examples_test.go
index 19d2d1ec139..e4ebd42f322 100644
--- a/examples/examples_test.go
+++ b/examples/examples_test.go
@@ -115,9 +115,6 @@ func walkJSONFiles(inDir string, fn func(name, path string, data []byte)) error
 
 func TestExampleObjectSchemas(t *testing.T) {
 	cases := map[string]map[string]runtime.Object{
-		"../docs/getting-started-guides": {
-			"pod": &api.Pod{},
-		},
 		"../cmd/integration": {
 			"v1beta1-controller": &api.ReplicationController{},
 			"v1beta3-controller": &api.ReplicationController{},
@@ -177,6 +174,10 @@ func TestExampleObjectSchemas(t *testing.T) {
 		"../examples/glusterfs/v1beta3": {
 			"glusterfs": &api.Pod{},
 		},
+		"../examples": {
+			"pod":         &api.Pod{},
+			"replication": &api.ReplicationController{},
+		},
 	}
 
 	for path, expected := range cases {
@@ -225,14 +226,18 @@ var sampleRegexp = regexp.MustCompile("(?ms)^```(?:(?P<type>yaml)\\w*\\n(?P<cont
 var subsetRegexp = regexp.MustCompile("(?ms)\\.{3}")
 
 func TestReadme(t *testing.T) {
-	paths := []string{
-		"../README.md",
-		"../examples/walkthrough/README.md",
-		"../examples/iscsi/README.md",
+	paths := []struct {
+		file         string
+		expectedType []runtime.Object
+	}{
+		{"../README.md", []runtime.Object{&api.Pod{}}},
+		{"../examples/walkthrough/README.md", []runtime.Object{&api.Pod{}}},
+		{"../examples/iscsi/README.md", []runtime.Object{&api.Pod{}}},
+		{"../examples/simple-yaml.md", []runtime.Object{&api.Pod{}, &api.ReplicationController{}}},
 	}
 
 	for _, path := range paths {
-		data, err := ioutil.ReadFile(path)
+		data, err := ioutil.ReadFile(path.file)
 		if err != nil {
 			t.Errorf("Unable to read file %s: %v", path, err)
 			continue
@@ -242,6 +247,7 @@ func TestReadme(t *testing.T) {
 		if matches == nil {
 			continue
 		}
+		ix := 0
 		for _, match := range matches {
 			var content, subtype string
 			for i, name := range sampleRegexp.SubexpNames() {
@@ -257,8 +263,13 @@ func TestReadme(t *testing.T) {
 				continue
 			}
 
-			//t.Logf("testing (%s): \n%s", subtype, content)
-			expectedType := &api.Pod{}
+			var expectedType runtime.Object
+			if len(path.expectedType) == 1 {
+				expectedType = path.expectedType[0]
+			} else {
+				expectedType = path.expectedType[ix]
+				ix++
+			}
 			json, err := yaml.ToJSON([]byte(content))
 			if err != nil {
 				t.Errorf("%s could not be converted to JSON: %v\n%s", path, err, string(content))
diff --git a/examples/pod.yaml b/examples/pod.yaml
new file mode 100644
index 00000000000..c5eb91f988a
--- /dev/null
+++ b/examples/pod.yaml
@@ -0,0 +1,16 @@
+apiVersion: v1beta3
+kind: Pod
+metadata:
+  labels:
+    name: nginx
+  name: nginx
+  namespace: default
+spec:
+  containers:
+  - image: nginx
+    imagePullPolicy: IfNotPresent
+    name: nginx
+    ports:
+    - containerPort: 80
+      protocol: TCP
+  restartPolicy: Always
\ No newline at end of file
diff --git a/examples/replication.yaml b/examples/replication.yaml
new file mode 100644
index 00000000000..6692777adf3
--- /dev/null
+++ b/examples/replication.yaml
@@ -0,0 +1,23 @@
+apiVersion: v1beta3
+kind: ReplicationController
+metadata:
+  name: nginx
+  namespace: default
+spec:
+  replicas: 3
+  selector:
+    app: nginx
+  template:
+    metadata:
+      name: nginx
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - image: nginx
+        imagePullPolicy: IfNotPresent
+        name: nginx
+        ports:
+        - containerPort: 80
+          protocol: TCP
+      restartPolicy: Always
diff --git a/examples/simple-nginx.md b/examples/simple-nginx.md
new file mode 100644
index 00000000000..e8d1dd97ca1
--- /dev/null
+++ b/examples/simple-nginx.md
@@ -0,0 +1,44 @@
+## Running your first containers in Kubernetes
+
+Ok, you've run one of the [getting started guides](../docs/getting-started-guides/) and you have
+successfully turned up a Kubernetes cluster.  Now what?  This guide will help you get oriented
+to Kubernetes and running your first containers on the cluster.
+
+### Running a container (simple version)
+
+Assume that ```${KUBERNETES_HOME}``` points to the directory where you installed the kubernetes directory.
+
+Once you have your cluster created you can use ```${KUBERNETES_HOME/kubernetes/cluster/kubectl.sh``` to access
+the kubernetes api.
+
+The `kubectl.sh` line below spins up two containers running
+[Nginx](http://nginx.org/en/) running on port 80:
+
+```bash
+kubectl run-container my-nginx --image=nginx --replicas=2 --port=80
+```
+
+Once the pods are created, you can list them to see what is up and running:
+```base
+kubectl get pods
+```
+
+To stop the two replicated containers:
+
+```bash
+kubectl stop rc my-nginx
+```
+
+### Exposing your pods to the internet.
+On some platforms (for example Google Compute Engine) the kubectl command can integrate with your cloud provider to add a public IP address for the pods,
+to do this run:
+
+```bash
+kubectl expose rc nginx --port=80 --create-external-load-balancer
+```
+
+This should print the service that has been created, and map an external IP address to the service.
+
+### Next: Configuration files
+Most people will eventually want to use declarative configuration files for creating/modifying their applications.  A [simplified introduction](simple-yaml.md)
+is given in a different document.
\ No newline at end of file
diff --git a/examples/simple-yaml.md b/examples/simple-yaml.md
new file mode 100644
index 00000000000..c3e55c0d5be
--- /dev/null
+++ b/examples/simple-yaml.md
@@ -0,0 +1,89 @@
+## Getting started with config files.
+
+In addition to the imperative style commands described [elsewhere](simple-nginx.md), Kubernetes
+supports declarative YAML or JSON configuration files.  Often times config files are prefereable
+to imperative commands, since they can be checked into version control and changes to the files
+can be code reviewed, producing a more robust, reliable and archival system.
+
+### Running a container from a pod configuration file
+
+```bash
+cd kubernetes
+kubectl create -f pod.yaml
+```
+
+Where pod.yaml contains something like:
+
+```yaml
+apiVersion: v1beta3
+kind: Pod
+metadata:
+  labels:
+    app: nginx
+  name: nginx
+  namespace: default
+spec:
+  containers:
+  - image: nginx
+    imagePullPolicy: IfNotPresent
+    name: nginx
+    ports:
+    - containerPort: 80
+      protocol: TCP
+  restartPolicy: Always
+```
+
+You can see your cluster's pods:
+
+```bash
+kubectl get pods
+```
+
+and delete the pod you just created:
+
+```bash
+kubectl delete pods nginx
+```
+
+### Running a replicated set of containers from a configuration file
+To run replicated containers, you need a [Replication Controller](../docs/replication-controller.md).
+A replication controller is responsible for ensuring that a specific number of pods exist in the
+cluster.
+
+```bash
+cd kubernetes
+kubectl create -f replication.yaml
+```
+
+Where ```replication.yaml``` contains:
+
+```yaml
+apiVersion: v1beta3
+kind: ReplicationController
+metadata:
+  name: nginx
+  namespace: default
+spec:
+  replicas: 3
+  selector:
+    app: nginx
+  template:
+    metadata:
+      name: nginx
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - image: nginx
+        imagePullPolicy: IfNotPresent
+        name: nginx
+        ports:
+        - containerPort: 80
+          protocol: TCP
+      restartPolicy: Always
+```
+
+To delete the replication controller (and the pods it created):
+```bash
+kubectl delete rc nginx
+```