diff --git a/changelog.d/4801.feature b/changelog.d/4801.feature
new file mode 100644
index 0000000000000000000000000000000000000000..1e5fd324636c5b237d5e09e9a2e81c807de747eb
--- /dev/null
+++ b/changelog.d/4801.feature
@@ -0,0 +1 @@
+Include a default configuration file in the 'docs' directory.
diff --git a/docs/.sample_config_header.yaml b/docs/.sample_config_header.yaml
index 576fc98609937f7be5354b2cbe7f48ac6295a6bf..e001ef59833b7d33994e470924225d8d13468fcd 100644
--- a/docs/.sample_config_header.yaml
+++ b/docs/.sample_config_header.yaml
@@ -1,7 +1,12 @@
-# This file is a reference to the configuration options which can be set in
-# homeserver.yaml.
+# The config is maintained as an up-to-date snapshot of the default
+# homeserver.yaml configuration generated by Synapse.
 #
-# Note that it is not quite ready to be used as-is. If you are starting from
-# scratch, it is easier to generate the config files following the instructions
-# in INSTALL.md.
+# It is intended to act as a reference for the default configuration,
+# helping admins keep track of new options and other changes, and compare
+# their configs with the current default.  As such, many of the actual
+# config values shown are placeholders.
+#
+# It is *not* intended to be copied and used as the basis for a real
+# homeserver.yaml. Instead, if you are starting from scratch, please generate
+# a fresh config using Synapse by following the instructions in INSTALL.md.
 
diff --git a/docs/sample_config.yaml b/docs/sample_config.yaml
index 3dd0b4a1a888fe0b5a0973c5fe7fa8f924f3cb06..b62745dd6e251b4da3ed9e2bd729f3fff05ec29f 100644
--- a/docs/sample_config.yaml
+++ b/docs/sample_config.yaml
@@ -1,9 +1,14 @@
-# This file is a reference to the configuration options which can be set in
-# homeserver.yaml.
+# The config is maintained as an up-to-date snapshot of the default
+# homeserver.yaml configuration generated by Synapse.
 #
-# Note that it is not quite ready to be used as-is. If you are starting from
-# scratch, it is easier to generate the config files following the instructions
-# in INSTALL.md.
+# It is intended to act as a reference for the default configuration,
+# helping admins keep track of new options and other changes, and compare
+# their configs with the current default.  As such, many of the actual
+# config values shown are placeholders.
+#
+# It is *not* intended to be copied and used as the basis for a real
+# homeserver.yaml. Instead, if you are starting from scratch, please generate
+# a fresh config using Synapse by following the instructions in INSTALL.md.
 
 ## Server ##