diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
deleted file mode 100644
index 9537746e..00000000
--- a/CONTRIBUTING.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-=============================================
-Contributing to: heat-specs
-=============================================
-
-If you would like to contribute to the development of OpenStack,
-you must follow the steps in this page:
-
-   http://docs.openstack.org/infra/manual/developers.html
-
-Once those steps have been completed, changes to OpenStack
-should be submitted for review via the Gerrit tool, following
-the workflow documented at:
-
-   http://docs.openstack.org/infra/manual/developers.html#development-workflow
-
-Pull requests submitted through GitHub will be ignored.
-
-Bugs should be filed on Launchpad, not GitHub:
-
-   https://bugs.launchpad.net/heat
\ No newline at end of file
diff --git a/README.rst b/README.rst
index 63f45d4f..8818209f 100644
--- a/README.rst
+++ b/README.rst
@@ -1,13 +1,50 @@
-===============================
-heat-specs
-===============================
+=============================
+OpenStack Heat Specifications
+=============================
 
-Specs for Heat
+This git repository is used to hold approved design specifications for
+additions to the heat project. Reviews of the specs are done in gerrit,
+using a similar workflow to how we review and merge changes to the code
+itself.
 
-* Free software: Apache license
-* Documentation: https://specs.openstack.org/openstack/heat-specs/
+The layout of this repository is::
 
-Features
---------
+  specs/<release>/
 
-* TODO
+Specifications are proposed for a given release by adding them to the
+`specs/<release>` directory and posting it for review.  The implementation
+status of a blueprint for a given release can be found by looking at the
+blueprint in launchpad.  Not all approved blueprints will get fully
+implemented.
+
+You can find an example spec in `specs/template.rst`.
+
+There is a sub-directory specs/<release>/backlog to store all specs
+that had been approved but are not implemented in a specific release.
+
+Movement of specs to the backlog would be done in a batch at the end of
+a release cycle.
+
+Prior to the Juno development cycle, this repository was not used for spec
+reviews.  Reviews prior to Juno were completed entirely through Launchpad
+blueprints::
+
+  http://blueprints.launchpad.net/heat
+
+Please note, Launchpad blueprints are still used for tracking the
+current status of blueprints. For more information, see::
+
+  https://wiki.openstack.org/wiki/Blueprints
+
+For more information about working with gerrit, see::
+
+  http://docs.openstack.org/infra/manual/developers.html#development-workflow
+
+To validate that the specification is syntactically correct (i.e. get more
+confidence in the Jenkins result), please execute the following command::
+
+  $ tox
+
+After running ``tox``, the documentation will be available for viewing in HTML
+format in the ``doc/build/`` directory. Please do not checkin the generated
+HTML files as a part of your commit.
diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
deleted file mode 100644
index 9537746e..00000000
--- a/doc/source/contributing.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-=============================================
-Contributing to: heat-specs
-=============================================
-
-If you would like to contribute to the development of OpenStack,
-you must follow the steps in this page:
-
-   http://docs.openstack.org/infra/manual/developers.html
-
-Once those steps have been completed, changes to OpenStack
-should be submitted for review via the Gerrit tool, following
-the workflow documented at:
-
-   http://docs.openstack.org/infra/manual/developers.html#development-workflow
-
-Pull requests submitted through GitHub will be ignored.
-
-Bugs should be filed on Launchpad, not GitHub:
-
-   https://bugs.launchpad.net/heat
\ No newline at end of file
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 478c36ff..058b6e08 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -48,7 +48,6 @@ heat-specs Repository Information
    :maxdepth: 2
 
    README <readme>
-   contributing
 
 
 Indices and tables
diff --git a/doc/source/readme.rst b/doc/source/readme.rst
index 51296106..a6210d3d 100644
--- a/doc/source/readme.rst
+++ b/doc/source/readme.rst
@@ -1,13 +1 @@
-===============================
-heat-specs
-===============================
-
-Specs for Heat
-
-* Free software: Apache license
-* Documentation: http://specs.openstack.org/openstack/heat-specs
-
-Features
---------
-
-* TODO
+.. include:: ../../README.rst