write.wap.enabled / spark.wap.branch behavior isn't really documented

[wimlewis-amazon]

Feature Request / Improvement

It's unclear from reading the doc what the effect of setting write.wap.enabled actually is. I can make some assumptions based on the write-audit-publish example, but those assumptions are almost certainly incomplete (for example, there are edge cases and failure conditions that I would need to understand before applying this in production, but the example only shows the "happy path".). As a user of the Iceberg libraries, I would like the documentation to be more explicit about what changes if I set either of these configuration options.

Query engine

Spark

Willingness to contribute

• I can contribute this improvement/feature independently
• I would be willing to contribute this improvement/feature with guidance from the Iceberg community
• I cannot contribute this improvement/feature at this time