diff --git a/HACKING.rst b/HACKING.rst
index f8ca7db2..06aed643 100644
--- a/HACKING.rst
+++ b/HACKING.rst
@@ -315,7 +315,7 @@ OpenStack Trademark
 -------------------
 
 OpenStack is a registered trademark of the OpenStack Foundation, and uses the
-following capitalization:
+following capitalization::
 
    OpenStack
 
@@ -349,5 +349,4 @@ readable.
 For further information on constructing high quality commit messages,
 and how to split up commits into a series of changes, consult the
 project wiki:
-
-   https://wiki.openstack.org/GitCommitMessages
+https://wiki.openstack.org/GitCommitMessages
diff --git a/README.rst b/README.rst
index 083b6b6e..88a0c22a 100644
--- a/README.rst
+++ b/README.rst
@@ -10,9 +10,9 @@ introduce new rules, or make existing rules stricter.
 Installation
 ============
 
-hacking is available from pypi, so just run:
+hacking is available from pypi, so just run::
 
-  ``pip install hacking``
+  pip install hacking
 
 This will install specific versions of ``flake8`` with the ``hacking``,
 ``pep8``, ``mccabe`` and ``pyflakes`` plugins.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 8197024b..adcd65e8 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,9 +1,14 @@
-.. include:: ../../HACKING.rst
+================================================
+hacking: OpenStack Hacking Guideline Enforcement
+================================================
 
-Readme
-======
+hacking is a set of flake8 plugins that test and enforce the :ref:`StyleGuide`.
+
+Hacking pins its dependencies, as a new release of some dependency can break
+hacking based gating jobs. This is because new versions of dependencies can
+introduce new rules, or make existing rules stricter.
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 3
 
-   readme
+   user/index
diff --git a/doc/source/readme.rst b/doc/source/readme.rst
deleted file mode 100644
index a6210d3d..00000000
--- a/doc/source/readme.rst
+++ /dev/null
@@ -1 +0,0 @@
-.. include:: ../../README.rst
diff --git a/doc/source/user/hacking.rst b/doc/source/user/hacking.rst
new file mode 100644
index 00000000..96ab88ef
--- /dev/null
+++ b/doc/source/user/hacking.rst
@@ -0,0 +1 @@
+.. include:: ../../../HACKING.rst
diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst
new file mode 100644
index 00000000..23165d01
--- /dev/null
+++ b/doc/source/user/index.rst
@@ -0,0 +1,9 @@
+==================
+User Documentation
+==================
+
+.. toctree::
+   :maxdepth: 2
+
+   hacking
+   usage
diff --git a/doc/source/user/usage.rst b/doc/source/user/usage.rst
new file mode 100644
index 00000000..4b934742
--- /dev/null
+++ b/doc/source/user/usage.rst
@@ -0,0 +1,5 @@
+=============
+Using hacking
+=============
+
+.. include:: ../../../README.rst