diff --git a/crates/puffin-cli/tests/pip_install_scenarios.rs b/crates/puffin-cli/tests/pip_install_scenarios.rs
index 711e93287..ee6cf240e 100644
--- a/crates/puffin-cli/tests/pip_install_scenarios.rs
+++ b/crates/puffin-cli/tests/pip_install_scenarios.rs
@@ -1,9 +1,10 @@
+//! DO NOT EDIT
+//!
+//! Generated with ./scripts/scenarios/update.py
+//! Scenarios from <https://github.com/zanieb/packse/tree/c448e24b336f3699407c50ed7a07b9b7442cb1a5/scenarios>
+//!
 #![cfg(all(feature = "python", feature = "pypi"))]
 
-/// DO NOT EDIT
-///
-/// GENERATED WITH `./scripts/scenarios/update.py`
-/// SCENARIOS FROM `https://github.com/zanieb/packse/tree/d899bfe2c3c33fcb9ba5eac0162236a8e8d8cbcf/scenarios`
 use std::path::Path;
 use std::process::Command;
 
diff --git a/scripts/scenarios/template.mustache b/scripts/scenarios/template.mustache
index 12ac69b7b..a9f01ef53 100644
--- a/scripts/scenarios/template.mustache
+++ b/scripts/scenarios/template.mustache
@@ -1,11 +1,10 @@
-
+//! DO NOT EDIT
+//!
+//! Generated with {{generated_with}}
+//! Scenarios from <{{generated_from}}>
+//!
 #![cfg(all(feature = "python", feature = "pypi"))]
 
-/// DO NOT EDIT
-///
-/// GENERATED WITH `{{generated_with}}`
-/// SCENARIOS FROM `{{generated_from}}`
-
 use std::path::Path;
 use std::process::Command;
 
diff --git a/scripts/scenarios/update.py b/scripts/scenarios/update.py
index 1df49de6e..599d5416f 100755
--- a/scripts/scenarios/update.py
+++ b/scripts/scenarios/update.py
@@ -1,20 +1,41 @@
 #!/usr/bin/env python3
-#
-# Generates and updates snapshot test cases from packse scenarios.
-#
-# Usage:
-#
-#     $ ./scripts/scenarios/update.py
-#
-# Requirements:
-#
-#   Requires `packse` and `chevron-blue`.
-#
-#     $ pip install -r scripts/scenarios/requirements.txt
-#
-#   Also supports a local, editable requirement on `packse`.
-#
-#   Uses `git`, `rustfmt`, and `cargo insta test` requirements from the project.
+"""
+Generates and updates snapshot test cases from packse scenarios.
+
+Usage:
+
+    Regenerate the scenario test file:
+    
+        $ ./scripts/scenarios/update.py
+
+    Scenarios are pinned to a specific commit. Change the `PACKSE_COMMIT` constant to update them.
+
+    Scenarios can be developed locally with the following workflow:
+
+        Install the local version of packse
+
+        $ pip install -e <path to packse>
+
+        From the packse repository, build and publish the scenarios to a local index
+
+        $ packse index up --bg
+        $ packse build scenarios/*
+        $ packse publish dist/* --index-url http://localhost:3141/packages/local --anonymous
+
+        Override the default PyPI index for Puffin and update the scenarios
+
+        $ PUFFIN_INDEX_URL="http://localhost:3141/packages/all/+simple" ./scripts/scenarios/update.py
+
+Requirements:
+
+    Requires `packse` and `chevron-blue`.
+
+        $ pip install -r scripts/scenarios/requirements.txt
+
+    Also supports a local, editable requirement on `packse`.
+
+    Uses `git`, `rustfmt`, and `cargo insta test` requirements from the project.
+"""
 
 import json
 import shutil