diff --git a/docs/README.md b/docs/README.md
index e5474d524d..bbc741d593 100755
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,7 +4,7 @@ Docker Documentation
 Overview
 --------
 
-The source for Docker documentation is here under ``sources/`` and uses
+The source for Docker documentation is here under `sources/` and uses
 extended Markdown, as implemented by [mkdocs](http://mkdocs.org).
 
 The HTML files are built and hosted on `https://docs.docker.io`, and
@@ -16,36 +16,36 @@ the "master" documentation.
 
 ## Branches
 
-**There are two branches related to editing docs**: ``master`` and a
-``docs`` branch. You should always edit documentation on a local branch
-of the ``master`` branch, and send a PR against ``master``.
+**There are two branches related to editing docs**: `master` and a
+`docs` branch. You should always edit documentation on a local branch
+of the `master` branch, and send a PR against `master`.
 
 That way your fixes will automatically get included in later releases,
 and docs maintainers can easily cherry-pick your changes into the
-``docs`` release branch. In the rare case where your change is not
-forward-compatible, you may need to base your changes on the ``docs``
+`docs` release branch. In the rare case where your change is not
+forward-compatible, you may need to base your changes on the `docs`
 branch.
 
-Also, now that we have a ``docs`` branch, we can keep the
+Also, now that we have a `docs` branch, we can keep the
 [http://docs.docker.io](http://docs.docker.io) docs up to date with any
-bugs found between ``docker`` code releases.
+bugs found between `docker` code releases.
 
 **Warning**: When *reading* the docs, the
 [http://beta-docs.docker.io](http://beta-docs.docker.io) documentation
 may include features not yet part of any official docker release. The
-``beta-docs`` site should be used only for understanding bleeding-edge
-development and ``docs.docker.io`` (which points to the ``docs``
-branch``) should be used for the latest official release.
+`beta-docs` site should be used only for understanding bleeding-edge
+development and `docs.docker.io` (which points to the `docs`
+branch`) should be used for the latest official release.
 
 Getting Started
 ---------------
 
 Docker documentation builds are done in a Docker container, which
-installs all the required tools, adds the local ``docs/`` directory and
+installs all the required tools, adds the local `docs/` directory and
 builds the HTML docs. It then starts a HTTP server on port 8000 so that
 you can connect and see your changes.
 
-In the root of the ``docker`` source directory:
+In the root of the `docker` source directory:
 
     cd docker
 
@@ -53,13 +53,13 @@ Run:
 
     make docs
 
-If you have any issues you need to debug, you can use ``make docs-shell`` and
-then run ``mkdocs serve``
+If you have any issues you need to debug, you can use `make docs-shell` and
+then run `mkdocs serve`
 
 # Contributing
 
 * Follow the contribution guidelines ([see
-  ``../CONTRIBUTING.md``](../CONTRIBUTING.md)).
+  `../CONTRIBUTING.md`](../CONTRIBUTING.md)).
 * [Remember to sign your work!](../CONTRIBUTING.md#sign-your-work)
 
 Working using GitHub's file editor
@@ -67,7 +67,7 @@ Working using GitHub's file editor
 
 Alternatively, for small changes and typos you might want to use
 GitHub's built in file editor. It allows you to preview your changes
-right online (though there can be some differences between GitHub
+right on-line (though there can be some differences between GitHub
 Markdown and mkdocs Markdown). Just be careful not to create many commits.
 And you must still [sign your work!](../CONTRIBUTING.md#sign-your-work)
 
@@ -75,26 +75,24 @@ Images
 ------
 
 When you need to add images, try to make them as small as possible
-(e.g. as gif). Usually images should go in the same directory as the
-.md file which references them, or in a subdirectory if one already
+(e.g. as gifs). Usually images should go in the same directory as the
+`.md` file which references them, or in a subdirectory if one already
 exists.
 
 Publishing Documentation
 ------------------------
 
-To publish a copy of the documentation you need a ``docs/awsconfig``
+To publish a copy of the documentation you need a `docs/awsconfig`
 file containing AWS settings to deploy to. The release script will
 create an s3 if needed, and will then push the files to it.
 
-```
-[profile dowideit-docs]
-aws_access_key_id = IHOIUAHSIDH234rwf....
-aws_secret_access_key = OIUYSADJHLKUHQWIUHE......
-region = ap-southeast-2
-```
+    [profile dowideit-docs]
+    aws_access_key_id = IHOIUAHSIDH234rwf....
+    aws_secret_access_key = OIUYSADJHLKUHQWIUHE......
+    region = ap-southeast-2
 
-The ``profile`` name must be the same as the name of the bucket you are
-deploying to - which you call from the docker directory:
+The `profile` name must be the same as the name of the bucket you are
+deploying to - which you call from the `docker` directory:
 
-``make AWS_S3_BUCKET=dowideit-docs docs-release``
+    make AWS_S3_BUCKET=dowideit-docs docs-release