Thanks for starting this conversation, Manu! I agree 100%. Having well-organized docs is super important for the growth of the community. Happy to help out here.
I see there are a couple of issues already created with the "docs" label on github, https://github.com/apache/iceberg/issues?q=state%3Aopen%20label%3A%22docs%22 I'll comment on those tickets individually. Regarding the points you brought up in the original email, 1. "latest" doc is physically a symlink to the latest version (e.g. 1.9.0), and it would be clearer to present this as something like “$iceberg_version (latest)” in the navigation. +1 to this change. Looking at the "docs" sub menu, there's also "nightly" and it's the default when I navigate to "docs". I would just caution to be careful here esp if there's a URL change since Google caches some links. 2. Links to PyIceberg, IcebergRust, and IcebergGo are currently nested under Iceberg Java, making them hard to find. Elevating these to the top level would make them more accessible. +1, I'd like to include links referencing the sub-projects. - Iceberg-python and Iceberg-rust both have their own website. https://py.iceberg.apache.org/ & https://rust.iceberg.apache.org/ - Iceberg-go currently uses https://pkg.go.dev/github.com/apache/iceberg-go 3. Contents of (or links to) external integrations are not specific to a version of Iceberg Java and better moved out. 4. There is an "Integrations" submenu but it's not clear why AWS, Dell, JDBC and Nessie are in the submenu while others are not. 5. The list of integrations is also growing so it would be better to find a new home for them. +1 to all the above. This also reminds me of the previous discussion thread on documentation, https://lists.apache.org/thread/jnfnf886r4y8q3og668f02pbw8ym7pq6 I'd like to reorganize the tabs on the main site and perhaps add a new "Community" tab. I just created https://github.com/apache/iceberg/issues/13261 so I won't forget again :) Looking forward to these changes! Best, Kevin Liu On Thu, Jun 5, 2025 at 12:19 AM Eduard Tudenhöfner <etudenhoef...@apache.org> wrote: > I do agree that we need to restructure the site to make things less > cluttered and easier to find. Thanks Manu/Peter for working on this. > It would be great to have a few more reviewers that can help out here and > add their opinions about the restructure. > > Thanks > Eduard > > On Thu, Jun 5, 2025 at 3:26 AM Manu Zhang <owenzhang1...@gmail.com> wrote: > >> Hi all, >> >> I know you've been busy finalizing v3 spec and discussing new features in >> v4 spec. When you find time, could you take a look at this as well? >> I think well-organized docs are also important to further grow the >> project and the community. >> >> Thanks, >> Manu >> >> On Mon, May 26, 2025 at 11:01 AM Manu Zhang <owenzhang1...@gmail.com> >> wrote: >> >>> Hi all, >>> >>> I’ve noticed that the current Docs side navigation >>> <https://iceberg.apache.org/docs/nightly/> on the Iceberg website is >>> still primarily structured around Iceberg Java. However, the project has >>> evolved significantly, with many new language implementations and >>> integrations. I’d like to highlight a few issues and suggestions for >>> improvement >>> >>> 1. "latest" doc is physically a symlink to the latest version (e.g. >>> 1.9.0), and it would be clearer to present this as something like >>> “$iceberg_version (latest)” in the navigation. >>> 2. Links to PyIceberg, IcebergRust, and IcebergGo are currently nested >>> under Iceberg Java, making them hard to find. Elevating these to the top >>> level would make them more accessible. >>> 3. Contents of (or links to) external integrations are not specific to a >>> version of Iceberg Java and better moved out. >>> 4. There is an "Integrations" submenu but it's not clear why AWS, Dell, >>> JDBC and Nessie are in the submenu while others are not. >>> 5. The list of integrations is also growing so it would be better to >>> find a new home for them. >>> >>> I've opened issues for 1 >>> <https://github.com/apache/iceberg/issues/12917> and 2 >>> <https://github.com/apache/iceberg/issues/12910>, and Peter Nguyen has >>> kindly opened PRs to fix them. >>> However, I believe a more comprehensive restructure of the Docs side >>> navigation would better serve the community and reflect the project’s >>> evolution. >>> >>> I'd love to hear your thoughts. >>> >>> Thanks, >>> Manu >>> >>> >>>
