diff --git a/doc/build.zig.zon.md b/doc/build.zig.zon.md
index d0740a923760b23d41dac9354ed71d2b8a31cecd..dc3ac749a9f9a48109f71fe2e76b8921ec72b3d3 100644
--- a/doc/build.zig.zon.md
+++ b/doc/build.zig.zon.md
@@ -47,7 +47,8 @@ String.
 
 When updating this field to a new URL, be sure to delete the corresponding
 `hash`, otherwise you are communicating that you expect to find the old hash at
-the new URL.
+the new URL. If the contents of a URL change this will result in a hash mismatch
+which will prevent zig from using it.
 
 #### `hash`
 
diff --git a/lib/init/build.zig.zon b/lib/init/build.zig.zon
index c06abec206bdf4a77be176459a19054a14c33025..cb7229042fc8cdc26ed58982828fb2d648c4ac52 100644
--- a/lib/init/build.zig.zon
+++ b/lib/init/build.zig.zon
@@ -27,7 +27,8 @@
         //.example = .{
         //    // When updating this field to a new URL, be sure to delete the corresponding
         //    // `hash`, otherwise you are communicating that you expect to find the old hash at
-        //    // the new URL.
+        //    // the new URL. If the contents of a URL change this will result in a hash mismatch
+        //    // which will prevent zig from using it.
         //    .url = "https://example.com/foo.tar.gz",
         //
         //    // This is computed from the file contents of the directory of files that is