diff --git a/docs/envvars.html b/docs/envvars.html
index 51c930f013f..17d69dc4cd4 100644
--- a/docs/envvars.html
+++ b/docs/envvars.html
@@ -133,6 +133,8 @@ that variable is set), or else within .cache/mesa within the user's
 home directory.
 <li>MESA_GLSL - <a href="shading.html#envvars">shading language compiler options</a>
 <li>MESA_NO_MINMAX_CACHE - when set, the minmax index cache is globally disabled.
+<li>MESA_SHADER_CAPTURE_PATH - see <a href="shading.html#capture">Capturing Shaders</a></li>
+<li>MESA_SHADER_DUMP_PATH and MESA_SHADER_READ_PATH - see <a href="shading.html#replacement">Experimenting with Shader Replacements</a></li>
 </ul>
 
 
diff --git a/docs/shading.html b/docs/shading.html
index 8b4cfb36a1f..a0bbe997c1b 100644
--- a/docs/shading.html
+++ b/docs/shading.html
@@ -64,6 +64,7 @@ execution.  These are generally used for debugging.
 Example:  export MESA_GLSL=dump,nopt
 </p>
 
+<h3 id="replacement">Experimenting with Shader Replacements</h3>
 <p>
 Shaders can be dumped and replaced on runtime for debugging purposes. This
 feature is not currently supported by SCons build.
@@ -79,6 +80,20 @@ not clobber the replacement shaders. Also, the filenames of the replacement shad
 should match the filenames of the corresponding dumped shaders.
 </p>
 
+<h3 id="capture">Capturing Shaders</h3>
+
+<p>
+Setting <b>MESA_SHADER_CAPTURE_PATH</b> to a directory will cause the compiler
+to write <tt>.shader_test</tt> files for use with
+<a href="https://cgit.freedesktop.org/mesa/shader-db">shader-db</a>, a tool
+which compiler developers can use to gather statistics about shaders
+(instructions, cycles, memory accesses, and so on).
+</p>
+<p>
+Notably, this captures linked GLSL shaders - with all stages together -
+as well as ARB programs.
+</p>
+
 <h2 id="support">GLSL Version</h2>
 
 <p>