diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
index 4531cbd3b261..aaa04d464f30 100644
--- a/lib/matplotlib/pyplot.py
+++ b/lib/matplotlib/pyplot.py
@@ -1,5 +1,9 @@
-# Note: The first part of this file can be modified in place, but the latter
-# part is autogenerated by the boilerplate.py script.
+# Note: The first part of this file is hand-written and must be edited
+# in-place. The second part, starting with
+#   ### REMAINING CONTENT GENERATED BY boilerplate.py ###
+# is generated by the script boilerplate.py. It must not be edited here
+# because all changes will be overwritten by the next run of the script.
+# For more information see the description in boilerplate.py.
 
 """
 `matplotlib.pyplot` is a state-based interface to matplotlib. It provides
diff --git a/tools/boilerplate.py b/tools/boilerplate.py
index 11ec15ac1c44..a617d12c7072 100644
--- a/tools/boilerplate.py
+++ b/tools/boilerplate.py
@@ -1,12 +1,19 @@
 """
 Script to autogenerate pyplot wrappers.
 
-When this script is run, the current contents of pyplot are
-split into generatable and non-generatable content (via the magic header
-:attr:`PYPLOT_MAGIC_HEADER`) and the generatable content is overwritten.
-Hence, the non-generatable content should be edited in the pyplot.py file
-itself, whereas the generatable content must be edited via templates in
-this file.
+pyplot.py consists of two parts: a hand-written part at the top, and an
+automatically generated part at the bottom, starting with the comment
+
+  ### REMAINING CONTENT GENERATED BY boilerplate.py ###
+
+This script generates the automatically generated part of pyplot.py. It
+consists of colormap setter functions and wrapper functions for methods
+of Figure and Axes. Whenever the API of one of the wrapped methods changes,
+this script has to be rerun to keep pyplot.py up to date.
+
+The test ``lib/matplotlib/test_pyplot.py::test_pyplot_up_to_date`` checks
+that the autogenerated part of pyplot.py is up to date. It will fail in the
+case of an API mismatch and remind the developer to rerun this script.
 """
 
 # Although it is possible to dynamically generate the pyplot functions at