3 files changed, 7 insertions, 8 deletions
diff --git a/changelog.d/7272.doc b/changelog.d/7272.doc
new file mode 100644
index 0000000000..13a1ee340d
--- /dev/null
+++ b/changelog.d/7272.doc
@@ -0,0 +1 @@
+Documentation of media_storage_providers options updated to avoid misunderstandings. Contributed by Tristan Lins.
\ No newline at end of file
diff --git a/docs/sample_config.yaml b/docs/sample_config.yaml
index 81dccbd997..5ff1be4ebc 100644
--- a/docs/sample_config.yaml
+++ b/docs/sample_config.yaml
@@ -735,12 +735,11 @@ media_store_path: "DATADIR/media_store"
 #
 #media_storage_providers:
 #  - module: file_system
-#    # Whether to write new local files.
+#    # Whether to store newly uploaded local files
 #    store_local: false
-#    # Whether to write new remote media
+#    # Whether to store newly downloaded remote files
 #    store_remote: false
-#    # Whether to block upload requests waiting for write to this
-#    # provider to complete
+#    # Whether to wait for successful storage for local uploads
 #    store_synchronous: false
 #    config:
 #       directory: /mnt/some/other/directory
diff --git a/synapse/config/repository.py b/synapse/config/repository.py
index 7193ea1114..9d2ce20220 100644
--- a/synapse/config/repository.py
+++ b/synapse/config/repository.py
@@ -224,12 +224,11 @@ class ContentRepositoryConfig(Config):
         #
         #media_storage_providers:
         #  - module: file_system
-        #    # Whether to write new local files.
+        #    # Whether to store newly uploaded local files
         #    store_local: false
-        #    # Whether to write new remote media
+        #    # Whether to store newly downloaded remote files
         #    store_remote: false
-        #    # Whether to block upload requests waiting for write to this
-        #    # provider to complete
+        #    # Whether to wait for successful storage for local uploads
         #    store_synchronous: false
         #    config:
         #       directory: /mnt/some/other/directory