diff --git a/src/doc/src/reference/build-script-examples.md b/src/doc/src/reference/build-script-examples.md
index 1e4d230dd8d..567870c5c6c 100644
--- a/src/doc/src/reference/build-script-examples.md
+++ b/src/doc/src/reference/build-script-examples.md
@@ -86,6 +86,13 @@ There’s a couple of points of note here:
   such crate as a dependency, because there's an *implicit* invariant that
   sources in `.cargo/registry` should be immutable. `cargo` won't allow such
   scripts when packaging.
+  * Sometimes, projects want to check in a generated file, and treat it as
+    source code. However, in this case, the file shouldn't be generated from
+    `build.rs`. Instead, have a test or similar which checks that the file
+    precisely matches the generated version *and fails if the result doesn't
+    match*, and run that test as part of your CI. (The test can generate a
+    temporary file to compare to, and if you want to update the generated file,
+    you can replace the checked-in file with that temporary file.)
 * This script is relatively simple as it just writes out a small generated file.
   One could imagine that other more complex operations could take place such as
   generating a Rust module from a C header file or another language definition,