diff --git a/doc/source/index.rst b/doc/source/index.rst
index 93d2263ab..72ca4408d 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -4,7 +4,7 @@
    :maxdepth: 1
 
    install
-   deprecation
+   policy
    jobs
    roles
 
diff --git a/doc/source/deprecation.rst b/doc/source/policy.rst
similarity index 72%
rename from doc/source/deprecation.rst
rename to doc/source/policy.rst
index aab28b74d..dfb8c894d 100644
--- a/doc/source/deprecation.rst
+++ b/doc/source/policy.rst
@@ -1,5 +1,13 @@
+Policy
+======
+
+Below are some guidelines for developers contributing to `zuul-jobs`.
+
+.. contents::
+   :local:
+
 Deprecation Policy
-==================
+------------------
 
 Because `zuul-jobs` is intended for wide use by any Zuul, we try to
 take care when making backwards incompatible changes.
@@ -16,7 +24,7 @@ timeframe.  Otherwise, you may wish to temporarily switch to a local
 fork of `zuul-jobs` (or stop updating it if you already have).
 
 New Zuul Features
------------------
+*****************
 
 When a new feature is available in Zuul, the jobs in `zuul-jobs` may
 not be able to immediately take advantage of it.  We need to allow
@@ -26,14 +34,14 @@ after the first Zuul release with the required feature before merging
 a change to `zuul-jobs` which uses it.
 
 Deprecated Zuul Features
-------------------------
+************************
 
 Before deprecating a feature in Zuul which is used by `zuul-jobs`, the
 usage of the feature must be removed from `zuul-jobs` according to the
 deprecation policy described above.
 
 Python Version Policy
-=====================
+---------------------
 
 ``zuul-jobs`` targets Python 2.7 onwards and Python 3.5 onwards (note
 this differs slightly from Ansible upstream, where the policy is 2.6
@@ -44,6 +52,24 @@ Library code should be written to be compatible with both.  There are
 some tips on this in `Ansible and Python 3
 <https://docs.ansible.com/ansible/2.5/dev_guide/developing_python_3.html>`__.
 
+Role Variable Naming Policy
+---------------------------
+
+Variables referenced by roles from global scope (often intended to be
+set via ``host_vars`` and ``group_vars``, but also set during role
+inclusion) must be namespaced by prepending their role-name to the
+variable.  Thus ``example-role`` would have variables with names such
+as ``example_role_variable``; e.g.
+
+.. code-block:: yaml
+
+  tasks:
+    - name: Call "example" role
+      include_role:
+        name: example-role
+      vars:
+        example_role_variable: 'something'
+
 .. _zuul-announce: http://lists.zuul-ci.org/cgi-bin/mailman/listinfo/zuul-announce
 .. _zuul-discuss: http://lists.zuul-ci.org/cgi-bin/mailman/listinfo/zuul-discuss