diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 4e3a8611cc17ab501b8900bb85d30f0cfb5040dd..ad09fcb2649ab8e2dd59f0c368a38c4c7d749824 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -1,8 +1,17 @@
-Kayobe does not currently follow the upstream OpenStack development process,
-but we will still be incredibly grateful for any contributions.
+If you would like to contribute to the development of OpenStack, you must
+follow the steps in this page:
 
-Please raise issues and submit pull requests via Github.
+   http://docs.openstack.org/infra/manual/developers.html
 
-For team discussion we use the #openstack-kayobe IRC channel.
+If you already have a good understanding of how the system works and your
+OpenStack accounts are set up, you can skip to the development workflow
+section of this documentation to learn how changes to OpenStack should be
+submitted for review via the Gerrit tool:
 
-Thanks in advance!
+   http://docs.openstack.org/infra/manual/developers.html#development-workflow
+
+Pull requests submitted through GitHub will be ignored.
+
+Bugs should be filed on StoryBoard, not GitHub:
+
+   https://storyboard.openstack.org/
diff --git a/HACKING.rst b/HACKING.rst
new file mode 100644
index 0000000000000000000000000000000000000000..d559bfd83a138aac04314288321d9a39249daa44
--- /dev/null
+++ b/HACKING.rst
@@ -0,0 +1,4 @@
+kayobe Style Commandments
+===============================================
+
+Read the OpenStack Style Commandments https://docs.openstack.org/hacking/latest/
diff --git a/README.rst b/README.rst
index 3dbc7455e3153474142289be1cb0a9b49224a840..6956e72c2a8d49770c9af981b642c8ee2aa7dc90 100644
--- a/README.rst
+++ b/README.rst
@@ -2,21 +2,34 @@
 Kayobe
 ======
 
-.. image:: https://travis-ci.org/stackhpc/kayobe.svg?branch=master
-   :target: https://travis-ci.org/stackhpc/kayobe
+Kayobe enables deployment of containerised OpenStack to bare metal.
 
-Deployment of Scientific OpenStack using OpenStack kolla.
+Containers offer a compelling solution for isolating OpenStack services, but
+running the control plane on an orchestrator such as Kubernetes or Docker
+Swarm adds significant complexity and operational overheads.
 
-Kayobe is an open source tool for automating deployment of Scientific OpenStack
-onto a set of bare metal servers.  Kayobe is composed of Ansible playbooks, a
-python module, and makes heavy use of the OpenStack kolla project.  Kayobe aims
-to complement the kolla-ansible project, providing an opinionated yet highly
-configurable OpenStack deployment and automation of many operational
-procedures.
+The hosts in an OpenStack control plane must somehow be provisioned, but
+deploying a secondary OpenStack cloud to do this seems like overkill.
 
+Kayobe stands on the shoulders of giants:
+
+* OpenStack bifrost discovers and provisions the cloud
+* OpenStack kolla builds container images for OpenStack services
+* OpenStack kolla-ansible delivers painless deployment and upgrade of
+  containerised OpenStack services
+
+To this solid base, kayobe adds:
+
+* Configuration of cloud host OS & flexible networking
+* Management of physical network devices
+* A friendly openstack-like CLI
+
+All this and more, automated from top to bottom using Ansible.
+
+* Free software: Apache license
 * Documentation: https://kayobe.readthedocs.io/en/latest/
-* Source: https://github.com/stackhpc/kayobe
-* Bugs: https://github.com/stackhpc/kayobe/issues
+* Source: https://git.openstack.org/cgit/openstack/kayobe
+* Bugs: https://storyboard.openstack.org/
 * IRC: #openstack-kayobe
 
 Features
diff --git a/setup.cfg b/setup.cfg
index 563dabcd0b703aa074ccbffe584e54e215025a0d..d98b2b99525984ceefb2c95441e0edb809662cc3 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,19 +1,23 @@
 [metadata]
 name = kayobe
-summary = Deployment of Scientific OpenStack using OpenStack Kolla
+summary =
+    Deployment of OpenStack to bare metal using OpenStack kolla and bifrost
 description-file =
     README.rst
-author = Mark Goddard
-author-email = mark@stackhpc.com
-home-page = https://stackhpc.com
+author = OpenStack
+author-email = openstack-dev@lists.openstack.org
+home-page = https://kayobe.readthedocs.io/en/latest/
 classifier =
     Environment :: OpenStack
     Intended Audience :: Information Technology
     Intended Audience :: System Administrators
+    License :: OSI Approved :: Apache Software License
     Operating System :: POSIX :: Linux
     Programming Language :: Python
     Programming Language :: Python :: 2
     Programming Language :: Python :: 2.7
+    Programming Language :: Python :: 3
+    Programming Language :: Python :: 3.5
 
 [files]
 packages =
@@ -65,6 +69,7 @@ kayobe.cli=
 
 [build_sphinx]
 all-files = 1
+warning-is-error = 1
 source-dir = doc/source
 build-dir = doc/build
 
diff --git a/tox.ini b/tox.ini
index b77603a70b711da93d42a73271c3164f49dc6781..aac53e972a1e76dbb7a7aab547616e6d9761788c 100644
--- a/tox.ini
+++ b/tox.ini
@@ -31,12 +31,6 @@ commands =
 [testenv:venv]
 commands = {posargs}
 
-[testenv:docs]
-commands = python setup.py build_sphinx
-
-[testenv:debug]
-commands = oslo_debug_helper {posargs}
-
 [testenv:ansible]
 usedevelop = True
 # Create the virtualenv with access to system site packages, as this is
@@ -94,6 +88,12 @@ commands =
     coverage html -d cover
     coverage xml -o cover/coverage.xml
 
+[testenv:docs]
+commands = python setup.py build_sphinx
+
+[testenv:debug]
+commands = oslo_debug_helper {posargs}
+
 [flake8]
 # E123, E125 skipped as they are invalid PEP-8.