Hey Brian, Thanks for raising this. As a release manager, I can confirm that the current structure is confusing, and I can also see the community struggling with this because they are willing to contribute to the docs, but cannot always find the place where to do this. I think the complexity of the current website mostly comes from the versioned docs. It would be great if we can find a way to make this easier. Instead of using the branches, we could also use the release tags and build the docs for those versions.
I think switching to mkdocs-material is a great idea. We currently also use this for PyIceberg, and it works really well. My main concern is around merging everything together. Should we combine Java and Python in the same documentation? They have a different versioning scheme, so that would create a matrix of versions. Go and Rust <https://github.com/apache/iceberg-rust/issues/8> is also in the making, so that would explode at some point. Cheers, Fokko Ps. Currently, PyIceberg uses the gh-pages branch for publishing the docs <https://github.com/apache/iceberg/tree/gh-pages>. Op do 27 jul 2023 om 00:04 schreef Brian Olsen <bitsondata...@gmail.com>: > Hey all, > > I have some proposals I'd like to make to fixing the docs. I would want to > do this in two phases. > > The first phase I'm proposing that we locate all the documentation > (reference docs, website, and pyIceberg) back into the apache/iceberg > repository. I explain my reasoning in the attached document. This phase > would also update us from Hugo to MkDocs but keep all the content the same. > > The second phase, is focused on iteratively building out the content that > we've marked missing in some the proposal that Sam R. created along with a > recent community member, Mahfuza. We will also restructure the content to > following the diátaxis method (https://diataxis.fr/). > > > https://docs.google.com/document/d/1WJXzcwC6isfoywcLY2lZ9gZN6i0JU1I2SIZmCkumbZc/edit#heading=h.gli9mc2ghfz1 > > Let me know what you think and bring on the questions and criticisms > please! :) > > Bits >
