Document fast append tradeoffs

Author: kevinjqliu

mkdocs/docs/api.md

@@ -311,8 +311,8 @@ Next, write the data to the table. Both `append` and `overwrite` produce the sam
 
 <!-- prettier-ignore-start -->
 
-!!! note inline end "Merge append"
-    PyIceberg defaults to [merge append](https://iceberg.apache.org/spec/#snapshots), which automatically merges manifests when the configured threshold is reached. To minimize metadata written during a commit, set the table property `commit.manifest-merge.enabled` to `False` to use fast append instead.
+!!! note inline end "Merge and fast append"
+    PyIceberg defaults to [merge append](https://iceberg.apache.org/spec/#snapshots), which automatically merges manifests when the configured threshold is reached to keep metadata compact and reads performant. Fast append remains available by setting the table property `commit.manifest-merge.enabled` to `False`. Fast append minimizes the metadata written during a commit, enabling faster commits and reducing the possibility of conflicts, but accumulates more manifest metadata over time.
 
 <!-- prettier-ignore-end -->
 

mkdocs/docs/configuration.md

@@ -103,8 +103,8 @@ Iceberg tables support table properties to configure table behavior.
 
 <!-- prettier-ignore-start -->
 
-!!! note "Append mode"
-    PyIceberg defaults to [merge append](api.md#write-to-a-table). Set `commit.manifest-merge.enabled` to `False` on a table to use fast append instead.
+!!! note "Append modes"
+    PyIceberg defaults to [merge append](api.md#write-to-a-table) to keep manifest metadata compact. Set `commit.manifest-merge.enabled` to `False` on a table to use fast append, which writes less metadata during each commit but accumulates more manifests over time.
 
 <!-- prettier-ignore-end -->