laskoviymishka commented on PR #920: URL: https://github.com/apache/iceberg-go/pull/920#issuecomment-4287953767
One more thought on the sibling-projects angle, since I think it's actually the load-bearing argument here: [pyiceberg](https://github.com/apache/iceberg-python/blob/main/mkdocs/docs/api.md) and the Java site both hand-write code blocks inline, and that works for them, but both are very mature, slow-moving libraries where the spec-surface cadence is low enough that human diligence keeps the docs roughly aligned with the code. iceberg-go is in a different phase. Within the last release cycle alone we've shipped multi-table transactions, equality deletes (read + write + partitioned), compaction (Analyze + RewriteDataFiles + bin-pack), RowDelta, commit-conflict retry, multi-arg transforms, write/initial-default enforcement, and V3 preview pieces like row lineage and nanosecond timestamps. Hand-maintained docs fall behind that cadence almost immediately. The user-visible effect is worse than "slightly stale." Someone lands on go.iceberg.apache.org, sees a feature matrix with half the cells empty and a code sample that doesn't compile against the current API, and concludes the library is less mature than it actually is. That's a perception gap we close for free by making the compiled test the source of truth — the maintenance cost is the test you were going to write anyway, and `mdbook build` + the CI gate guarantee the site can never drift from it. Once iceberg-go's cadence matches pyiceberg/Java, the automation becomes less essential. Right now, it's the thing that lets the website keep pace with the code without asking contributors to do the duplicate work of pasting snippets by hand and hoping nobody notices when they rot. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
