diff --git a/playbooks/roles/ansible-cron/README.rst b/playbooks/roles/ansible-cron/README.rst
new file mode 100644
index 0000000000..bd8563dc32
--- /dev/null
+++ b/playbooks/roles/ansible-cron/README.rst
@@ -0,0 +1,21 @@
+Setup periodic runs of ``run_all.sh``, which runs playbooks against
+bridge.o.o and all hosts.
+
+**Role Variables**
+
+.. zuul:rolevar:: update_cron_interval
+
+   .. zuul:rolevar:: minute
+      :default: 15
+
+   .. zuul:rolevar:: hour
+      :default: *
+
+   .. zuul:rolevar:: day
+      :default: *
+
+   .. zuul:rolevar:: month
+      :default: *
+
+   .. zuul:rolevar:: weekday
+      :default: *
diff --git a/playbooks/roles/base-repos/README.rst b/playbooks/roles/base-repos/README.rst
new file mode 100644
index 0000000000..7a210301fb
--- /dev/null
+++ b/playbooks/roles/base-repos/README.rst
@@ -0,0 +1,5 @@
+Set basic repository sources
+
+**Role Variables**
+
+* None
diff --git a/playbooks/roles/base-server/README.rst b/playbooks/roles/base-server/README.rst
new file mode 100644
index 0000000000..de244c3a06
--- /dev/null
+++ b/playbooks/roles/base-server/README.rst
@@ -0,0 +1,5 @@
+Basic common server configuration
+
+**Role Variables**
+
+* None
diff --git a/playbooks/roles/disable-puppet-agent/README.rst b/playbooks/roles/disable-puppet-agent/README.rst
new file mode 100644
index 0000000000..f9f9bf91b8
--- /dev/null
+++ b/playbooks/roles/disable-puppet-agent/README.rst
@@ -0,0 +1,5 @@
+Disable the puppet-agent service on a host
+
+**Role Variables**
+
+* None
diff --git a/playbooks/roles/install-ansible/README.rst b/playbooks/roles/install-ansible/README.rst
new file mode 100644
index 0000000000..d6eaee5f43
--- /dev/null
+++ b/playbooks/roles/install-ansible/README.rst
@@ -0,0 +1,5 @@
+Install and configure Ansible on a host via pip
+
+**Role Variables**
+
+* None
diff --git a/playbooks/roles/pip3/README.rst b/playbooks/roles/pip3/README.rst
new file mode 100644
index 0000000000..b81002981d
--- /dev/null
+++ b/playbooks/roles/pip3/README.rst
@@ -0,0 +1,5 @@
+Install system packages for python3 pip and virtualenv
+
+**Role Variables**
+
+* None
diff --git a/playbooks/roles/root-keys/README.rst b/playbooks/roles/root-keys/README.rst
new file mode 100644
index 0000000000..b60f782bf3
--- /dev/null
+++ b/playbooks/roles/root-keys/README.rst
@@ -0,0 +1,7 @@
+Write out root SSH private key
+
+**Role Variables**
+
+.. zuul:rolevar:: root_rsa_key
+
+   The root key to place in ``/root/.ssh/id_rsa``
diff --git a/playbooks/roles/set-hostname/README.rst b/playbooks/roles/set-hostname/README.rst
new file mode 100644
index 0000000000..5fc2cdca20
--- /dev/null
+++ b/playbooks/roles/set-hostname/README.rst
@@ -0,0 +1,8 @@
+Set hostname
+
+Remove ``cloud-init`` and statically set the hostname, hosts and
+mailname
+
+**Role Variables**
+
+* None
diff --git a/playbooks/roles/users/README.rst b/playbooks/roles/users/README.rst
new file mode 100644
index 0000000000..3089a06e09
--- /dev/null
+++ b/playbooks/roles/users/README.rst
@@ -0,0 +1,26 @@
+Configure users on a server
+
+Configure users on a server.  Users are given sudo access
+
+**Role Variables**
+
+.. zuul:rolevar:: all_users
+   :default: {}
+
+   Dictionary of all users.  Each user needs a ``uid``, ``gid`` and ``key``
+
+.. zuul:rolevar:: base_users
+   :default: []
+
+   Users to install on all hosts
+
+.. zuul:rolevar:: extra_users
+   :default: []
+
+   Extra users to install on a specific host or group
+
+.. zuul:rolevar:: disabled_users
+   :default: []
+
+   Users who should be removed from all hosts
+
diff --git a/tools/check_readme.sh b/tools/check_readme.sh
new file mode 100755
index 0000000000..c82ef20317
--- /dev/null
+++ b/tools/check_readme.sh
@@ -0,0 +1,9 @@
+#!/bin/bash
+
+# Trivial script run from tox -e linters to ensure roles have a
+# README.rst attached
+
+if ! [ -f $1/README.rst ]; then
+    echo "*** Missing role documentation: $1/README.rst"
+    exit 1
+fi
diff --git a/tox.ini b/tox.ini
index ea8a97d99e..d3511bc5df 100644
--- a/tox.ini
+++ b/tox.ini
@@ -12,6 +12,8 @@ deps = -r{toxinidir}/test-requirements.txt
 [testenv:linters]
 whitelist_externals = bash
 commands =
+  bash -c "find playbooks/roles -maxdepth 1 -mindepth 1 -type d -print0 | \
+     xargs -t -n1 -0 {toxinidir}/tools/check_readme.sh"
   flake8
   {toxinidir}/tools/run-bashate.sh
   python3 {toxinidir}/tools/sorted_modules_env.py {toxinidir}/modules.env