diff --git a/doc/source/zuul.rst b/doc/source/zuul.rst
index 367bf19f64..c77fc945c0 100644
--- a/doc/source/zuul.rst
+++ b/doc/source/zuul.rst
@@ -198,6 +198,22 @@ Zuul Web is stateless so is safe to restart, however restarting it will result
 in a loss of connection for anyone watching a live-stream of a console log
 when the restart happens.
 
+Secrets
+-------
+
+In some cases it may be warranted to compare the decrypted plaintext of
+a secret from job configuration against a reference value while
+troubleshooting, since random padding means encrypting the same
+plaintext a second time will result in wholly different ciphertext. In
+order to avoid unintentional disclosure this should only be done when
+absolutely necessary, but it's possible to decrypt a secret locally on
+the scheduler server with a command like the following (just extract the
+secret ciphertext from the job configuration first to remove surrounding
+YAML, there is no need to recombine split lines)::
+
+  cat ciphertext.txt | sed 's/^ *//' | base64 -d | sudo openssl rsautl -decrypt -oaep -inkey \
+  /var/lib/zuul/keys/secrets/project/gerrit/openstack-infra/project-config/0.pem
+
 .. _zuul_github_projects:
 
 GitHub Projects