diff --git a/.github/workflows/pull-request-preview-cleanup.yml b/.github/workflows/pull-request-preview-cleanup.yml
index 8a0265d..8109145 100644
--- a/.github/workflows/pull-request-preview-cleanup.yml
+++ b/.github/workflows/pull-request-preview-cleanup.yml
@@ -1,3 +1,5 @@
+# Remove preview from surge
+# see `pull-request-preview.yml` for more context
 name: Clean up pull request surge preview
 
 on:
diff --git a/.github/workflows/pull-request-preview.yml b/.github/workflows/pull-request-preview.yml
index 43650b0..5ca332f 100644
--- a/.github/workflows/pull-request-preview.yml
+++ b/.github/workflows/pull-request-preview.yml
@@ -1,3 +1,23 @@
+# Deploy pull requests to surge, so multiple previews can exist at once
+# The deployments API is used to make the deployments visible in the pull request
+#   https://surge.sh/
+# to install surge:
+#   $ npm install --global surge
+# to log in to surge or create an account, run
+#   $ surge
+# to publish a folder as a static site, run
+#   $ surge --project <folder> --domain <example28928.surge.sh>
+#     or
+#   $ surge <folder>
+# to remove a site, run
+#   $ surge teardown <example28928.surge.sh>
+# to list active sites, run
+#   $ surge list
+# this workflow requires two secrets: SURGE_LOGIN (the email you use above) and SURGE_TOKEN, generated with
+#   $ surge token
+# note: the PDFs are not deployed, as they turn a ~60mb site into a ~600mb site.
+# workflow modified from https://sanderknape.com/2020/05/deploy-pull-requests-github-actions-deployments/
+
 name: Deploy pull request preview to surge
 
 on: