diff --git a/docs/README.md b/docs/README.md
index 74ab2bd0cd..1a40b5bb5c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,14 +1,12 @@
-Docker documentation and website
-================================
+Docker Documentation
+====================
 
 Documentation
 -------------
-This is your definite place to contribute to the docker documentation. The documentation is generated from the
-.rst files under sources.
-
-The folder also contains the other files to create the http://docker.io website, but you can generally ignore
-most of those.
+This is your definite place to contribute to the docker documentation. After each push to master the documentation
+is automatically generated and made available on [docs.docker.io](http://docs.docker.io)
 
+Each of the .rst files under sources reflects a page on the documentation. 
 
 Installation
 ------------
@@ -36,15 +34,11 @@ Images
 ------
 When you need to add images, try to make them as small as possible (e.g. as gif).
 
-
 Notes
 -----
-* The index.html and gettingstarted.html files are copied from the source dir to the output dir without modification.
-So changes to those pages should be made directly in html
 * For the template the css is compiled from less. When changes are needed they can be compiled using
 lessc ``lessc main.less`` or watched using watch-lessc ``watch-lessc -i main.less -o main.css``
 
-
 Guides on using sphinx
 ----------------------
 * To make links to certain pages create a link target like so:
@@ -75,3 +69,12 @@ Guides on using sphinx
 * Code examples
 
   Start without $, so it's easy to copy and paste.
+
+Manpages
+--------
+
+* To make the manpages, simply run 'make man'. Please note there is a bug in spinx 1.1.3 which makes this fail.
+Upgrade to the latest version of sphinx.
+* Then preview the manpage by running `man _build/man/docker.1`, where _build/man/docker.1 is the path to the generated
+manfile
+* The manpages are also autogenerated by our hosted readthedocs here: http://docs-docker.dotcloud.com/projects/docker/downloads/
diff --git a/docs/sources/conf.py b/docs/sources/conf.py
index ea8e1f43f0..b4c23f0c58 100644
--- a/docs/sources/conf.py
+++ b/docs/sources/conf.py
@@ -203,7 +203,7 @@ latex_elements = {
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'Docker.tex', u'Docker Documentation',
+  ('toctree', 'Docker.tex', u'Docker Documentation',
    u'Team Docker', 'manual'),
 ]
 
@@ -233,7 +233,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'docker', u'Docker Documentation',
+    ('toctree', 'docker', u'Docker Documentation',
      [u'Team Docker'], 1)
 ]
 
@@ -247,7 +247,7 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'Docker', u'Docker Documentation',
+  ('toctree', 'Docker', u'Docker Documentation',
    u'Team Docker', 'Docker', 'One line description of project.',
    'Miscellaneous'),
 ]
diff --git a/docs/sources/use/builder.rst b/docs/sources/use/builder.rst
index 9f5ee8b795..d111e335ab 100644
--- a/docs/sources/use/builder.rst
+++ b/docs/sources/use/builder.rst
@@ -107,8 +107,8 @@ the image.  This is functionally equivalent to running ``docker commit
 -run '{"Cmd": <command>}'`` outside the builder.
 
 .. note::
-    Don't confuse `RUN` with `CMD`. `RUN` actually runs a
-    command and commits the result; `CMD` does not execute anything at
+    Don't confuse ``RUN`` with ``CMD``. ``RUN`` actually runs a
+    command and commits the result; ``CMD`` does not execute anything at
     build time, but specifies the intended command for the image.
 
 3.5 EXPOSE