diff --git a/playbooks/web-ext-lint/README.rst b/playbooks/web-ext-lint/README.rst
new file mode 100644
index 0000000..efaed6b
--- /dev/null
+++ b/playbooks/web-ext-lint/README.rst
@@ -0,0 +1,18 @@
+Check a Web Extension project for basic lint problems.
+
+**Job Variables**
+
+.. zuul:jobvar:: source_dir
+   :default: src
+
+   Folder where the uncompressed extension files are located (if you use a tool
+   –such as Webpack– to build your extension, this folder should have the
+   compiled files which you would ZIP and upload to the extensions store. If
+   this is a relative path, it is computed as if you were in the directory
+   ``{{ zuul.project.src_dir }}``.
+
+.. zuul:jobvar:: extra_lint_flags
+
+   Optional: string with flags that will be passed to the web-ext lint command,
+   if specified.
+
diff --git a/zuul.d/jobs.yaml b/zuul.d/jobs.yaml
index 26bc4e6..b3f6cbc 100644
--- a/zuul.d/jobs.yaml
+++ b/zuul.d/jobs.yaml
@@ -3,4 +3,4 @@
     pre-run: playbooks/web-ext-lint/pre.yaml
     run: playbooks/web-ext-lint/run.yaml
     post-run: playbooks/web-ext-lint/post.yaml
-    description: Check a Web Extension project for basic lint problems.
+    description: ".. include:: ../playbooks/web-ext-lint/README.rst"
diff --git a/zuul.d/test-jobs.yaml b/zuul.d/test-jobs.yaml
index 4221995..33ca91b 100644
--- a/zuul.d/test-jobs.yaml
+++ b/zuul.d/test-jobs.yaml
@@ -2,24 +2,28 @@
 
 - job:
     name: test-ensure-web-ext
+    description: Test the ensure-web-ext role
     run: playbooks/test-ensure-web-ext.yaml
     files:
       - roles/ensure-web-ext/.*
 
 - job:
     name: test-install-build-essential
+    description: Test the install-build-essential role
     run: playbooks/test-install-build-essential.yaml
     files:
       - roles/install-build-essential/.*
 
 - job:
     name: test-ensure-genmanifest
+    description: Test the ensure-genmanifest role
     run: playbooks/test-ensure-genmanifest.yaml
     files:
       - roles/ensure-genmanifest/.*
 
 - job:
     name: test-ensure-cws-upload
+    description: Test the ensure-cws-upload role
     run: playbooks/test-ensure-cws-upload.yaml
     files:
       - roles/ensure-cws-upload/.*