diff --git a/roles/upload-afs-synchronize/README.rst b/roles/upload-afs-synchronize/README.rst
index c2c902f1e..a3bc13bf1 100644
--- a/roles/upload-afs-synchronize/README.rst
+++ b/roles/upload-afs-synchronize/README.rst
@@ -1,8 +1,17 @@
-Copy contents from ``{{ zuul.executor.work_root }}/artifacts/`` to AFS
+Copy contents of a directory hierarchy to AFS
+
+This role uses the ``synchronzie`` module to copy directory contents
+to a remote AFS locations. It ensures the ``synchronize`` flags,
+particularly relating to group and world permissions, are appropriate
+for copying to AFS locations.
+
+See also :zuul:role:`upload-afs-roots` which is a similar role giving
+more fine-grained control over which directories are synchronized.
 
 **Role Variables**
 
 .. zuul:rolevar:: afs_source
+   :default: ``{{ zuul.executor.work_root }}/artifacts/``
 
   Path to local source directory.