diff --git a/README.md b/README.md
index 5d3767fc85..f18f59d13d 100644
--- a/README.md
+++ b/README.md
@@ -28,12 +28,12 @@ details.
 
 The Kolla developers build images in the kollaglue namespace for the following
 services:
-Glance
-Heat
-Keystone
-Mariadb
-Nova
-Rabbitmq
+* Glance
+* Heat
+* Keystone
+* Mariadb
+* Nova
+* Rabbitmq
 
 ```
 $ sudo docker search kollaglue
@@ -65,37 +65,50 @@ the templates from working).
 
 Here are some simple steps to get things rolling using the Heat templates:
 
-1. git clone https://github.com/larsks/heat-kubernetes/; cd heat-kubernetes
+1. Clone the repository:
+   ```
+   git clone https://github.com/larsks/heat-kubernetes/
+   cd heat-kubernetes
+   ```
 
-2. Create an appropriate image by running the get_image.sh script in this repository.  This will generate an image called "fedora-20-k8s.qcow2". Upload this image to Glance.  You can also obtain an appropriate image from
-https://fedorapeople.org/groups/heat/kolla/fedora-20-k8s.qcow2
+2. Create an appropriate image by running the get_image.sh script in this
+   repository.  This will generate an image called `fedora-20-k8s.qcow2`.
+   Upload this image to Glance.  You can also obtain an appropriate image from
+   https://fedorapeople.org/groups/heat/kolla/fedora-20-k8s.qcow2
 
-3. Create a file "local.yaml" with settings appropriate to your OpenStack environment. It should look something like:
-
-parameters:
-  server_image: fedora-20-k8s
-  ssh_key_name: sdake
+3. Create a file `local.yaml` with settings appropriate to your OpenStack
+   environment. It should look something like:
+   ```
+   parameters:
+     server_image: fedora-20-k8s
+     ssh_key_name: sdake
 
 
-  dns_nameserver: 8.8.8.8
-  external_network_id: 6e7e7701-46a0-49c0-9f06-ac5abc79d6ae
-  number_of_minions: 1
-  server_flavor: m1.large
+     dns_nameserver: 8.8.8.8
+     external_network_id: 6e7e7701-46a0-49c0-9f06-ac5abc79d6ae
+     number_of_minions: 1
+     server_flavor: m1.large
+   ```
+   You *must* provide settings for external_network_id and ssh_key_name; these
+   are local to your environment. You will probably also need to provide
+   a value for server_image, which should be the name (or UUID) of a Fedora 20
+   cloud image or derivative.
 
-You *must* provide settings for external_network_id and ssh_key_name; these are
-local to your environment. You will probably also need to provide a value for
-server_image, which should be the name (or UUID) of a Fedora 20 cloud image or
-derivative.
+4. `heat stack-create -f kubecluster.yaml -e local.yaml my-kube-cluster`
 
-4. heat stack-create -f kubecluster.yaml -e local.yaml my-kube-cluster
 5. Determine the ip addresses of your cluster hosts by running:
+   ```
+   heat output-show my-kube-cluster kube_minions_external
+   ```
 
-    heat output-show my-kube-cluster kube_minions_external
+6. Connect to the minion node with `ssh fedora@${minion-ip}`
 
-6. ssh fedora@${minion-ip}
-7. minion$ git clone http://github.com/stackforge/kolla
-8. minion$ cd kolla
-9. minion$ ./tools/start
+7. On the minion node:
+   ```
+   minion$ git clone http://github.com/stackforge/kolla
+   minion$ cd kolla
+   minion$ ./tools/start
+   ```
 
 Debugging
 ==========
@@ -105,15 +118,15 @@ A few commands for debugging the system.
 $ sudo docker images
 ```
 Lists all images that have been pulled from the upstream kollaglue repository
-thus far.  This can be run on the minion during the ./start operation to check
-on the download progress.
+thus far.  This can be run on the minion during the `./start` operation to
+check on the download progress.
 
 
 ```
 $ sudo docker ps -a
 ```
-This will show all processes that docker has started.  Removing the -a will
-show only active processes.  This can be run on the minion during the ./start
+This will show all processes that docker has started.  Removing the `-a` will
+show only active processes.  This can be run on the minion during the `./start`
 operation to check that the containers are orchestrated.
 
 
@@ -121,8 +134,8 @@ operation to check that the containers are orchestrated.
 $ sudo docker logs <containerid>
 ```
 This shows the logging output of each service in a container.  The containerid
-can be obtained via the docker ps operation.  This can be run on the minion
-during the ./start operation to debug the container.
+can be obtained via the `docker ps` operation.  This can be run on the minion
+during the `./start` operation to debug the container.
 
 ```
 $ kubecfg list pods
@@ -157,12 +170,14 @@ $ telnet minion_ip 3306
 This shows that the Mariadb service is running on the minions.  Output should
 appear as follows
 
+```
 $ telnet 10.0.0.4 3306
 Trying 10.0.0.4...
 Connected to 10.0.0.4.
 Escape character is '^]'.
 
 5.5.39-MariaDB-wsrep
+```
 
 If the connection closes before mysql responds then the proxy is not properly
 connecting to the database.  This can be seen by using jounalctl and watching
@@ -179,6 +194,7 @@ openvswitch on both nodes. This has usually fixed the connection issues.
 Directories
 ===========
 
-* docker - contains artifacts for use with docker build to build appropriate images
+* docker - contains artifacts for use with docker build to build appropriate
+  images
 * k8s - contains service and pod configuration information for Kubernetes
 * tools - contains different tools for interacting with Kolla