diff --git a/doc/source/admin/components.rst b/doc/source/admin/components.rst
index cc9d181..99912d7 100644
--- a/doc/source/admin/components.rst
+++ b/doc/source/admin/components.rst
@@ -317,6 +317,24 @@
 
      user=zuul
 
+.. _admin_sitewide_variables:
+
+**variables**
+  Path to an Ansible variables file to supply site-wide variables.
+  This should be a YAML-formatted file consisting of a single
+  dictionary.  The contents will be made available to all jobs as
+  Ansible variables.  These variables take precedence over all other
+  forms (job variables and secrets).  Care should be taken when naming
+  these variables to avoid potential collisions with those used by
+  jobs.  Prefixing variable names with a site-specific identifier is
+  recommended.  The default is not to add any site-wide variables.
+  See the :ref:`User's Guide <user_sitewide_variables>` for more
+  information.
+
+  Example::
+
+     variables=/etc/zuul/variables.yaml
+
 merger
 """"""
 
diff --git a/doc/source/user/jobs.rst b/doc/source/user/jobs.rst
index a367aa0..1812bc5 100644
--- a/doc/source/user/jobs.rst
+++ b/doc/source/user/jobs.rst
@@ -73,6 +73,24 @@
 Variables
 ---------
 
+There are several sources of variables which are available to Ansible:
+variables defined in jobs, secrets, and site-wide variables.  The
+order of precedence is:
+
+* Site-wide variables
+
+* Secrets
+
+* Job variables
+
+Meaning that a site-wide variable with the same name as any other will
+override its value, and similarly, secrets override job variables of
+the same name.  Each of the three sources is described below.
+
+
+Job Variables
+~~~~~~~~~~~~~
+
 Any variables specified in the job definition are available as Ansible
 host variables.  They are added to the `vars` section of the inventory
 file under the `all` hosts group, so they are available to all hosts.
@@ -293,6 +311,19 @@
 **zuul.executor.log_root**
   The path to the logs directory.
 
+
+.. _user_sitewide_variables:
+
+Site-wide Variables
+~~~~~~~~~~~~~~~~~~~
+
+The Zuul administrator may define variables which will be available to
+all jobs running in the system.  These are statically defined and may
+not be altered by jobs.  See the :ref:`Administrator's Guide
+<admin_sitewide_variables>` for information on how a site
+administrator may define these variables.
+
+
 SSH Keys
 --------