diff --git a/docs/api/delta_writer.md b/docs/api/delta_writer.md
index 432a32b768..9b395d3604 100644
--- a/docs/api/delta_writer.md
+++ b/docs/api/delta_writer.md
@@ -8,6 +8,8 @@ search:
 
 ::: deltalake.write_deltalake
 
+::: deltalake.WriterProperties
+
 ## Convert to Delta Tables
 ::: deltalake.convert_to_deltalake
 
diff --git a/python/deltalake/table.py b/python/deltalake/table.py
index 76b1dd4f49..b41e62bd07 100644
--- a/python/deltalake/table.py
+++ b/python/deltalake/table.py
@@ -1178,7 +1178,10 @@ def with_writer_properties(
         write_batch_size: Optional[int] = None,
         max_row_group_size: Optional[int] = None,
     ) -> "TableMerger":
-        """Pass writer properties to the Rust parquet writer, see options https://arrow.apache.org/rust/parquet/file/properties/struct.WriterProperties.html:
+        """
+        !!! warning "Deprecated"
+            Use `.merge(writer_properties = WriterProperties())` instead
+        Pass writer properties to the Rust parquet writer, see options https://arrow.apache.org/rust/parquet/file/properties/struct.WriterProperties.html:
 
         Args:
             data_page_size_limit: Limit DataPage size to this in bytes.