diff --git a/roles/add-fileserver/README.rst b/roles/add-fileserver/README.rst
index 8a7b5ecb1..ae7d74158 100644
--- a/roles/add-fileserver/README.rst
+++ b/roles/add-fileserver/README.rst
@@ -7,7 +7,23 @@ in subsequent tasks or roles.
 
    Complex argument which contains the information about the remote
    destination as well as the authentication information needed. It is
-   expected that this argument comes from a `Secret`.
+   expected that this argument comes from a `Secret
+   <https://zuul-ci.org/docs/zuul/user/config.html#secret>`_
+
+   Example:
+
+   .. code-block:: yaml
+
+      - secret:
+          name: site_logs
+            data:
+              fqdn: logs.example.org
+              path: /srv/static/logs
+              ssh_known_hosts: |
+                logs.example.org ssh-rsa ...
+              ssh_username: zuul
+              ssh_private_key: !encrypted/pkcs1-oaep
+                - ...
 
    .. zuul:rolevar:: fqdn
 
diff --git a/roles/upload-logs/README.rst b/roles/upload-logs/README.rst
index e9e51f4ad..6669f3d21 100644
--- a/roles/upload-logs/README.rst
+++ b/roles/upload-logs/README.rst
@@ -1,6 +1,22 @@
 Upload logs to a static webserver
 
-This uploads logs to a static webserver using SSH.
+This uploads logs to a static server using SSH.  The server must have
+been previously added to the inventory; this can be done with the
+:zuul:role:`add-fileserver` role; see that role's documentation for a
+description of the site_logs secret in this example post-run playbook:
+
+.. code-block:: yaml
+
+   - hosts: localhost
+     roles:
+       - role: add-fileserver
+         fileserver: "{{ site_logs }}"
+
+   - hosts: "{{ site_logs.fqdn }}"
+     gather_facts: False
+     roles:
+       - role: upload-logs
+         zuul_log_url: "http://logs.example.org"
 
 **Role Variables**