Hi I'm ok with putting things back in Iceberg repo, it gets more visbility on prs. I guess it used to be a bit distracting, but now with more projects in Iceberg (pyiceberg, rust) we have to anyway use tags to filter through all the mails.
Just wanted to +1 on Fokko/Ryan suggestion to avoid versioned doc directories, I had a lot of difficulties in this part doing the last release: https://github.com/apache/iceberg/issues/8151 , as did Anton when I consulted him offline. For me, replacing the 'latest' branch with a tag would be the biggest win as it caused me the most trouble. If we can avoid versioned docs and use tags across the board, that would be even better, I do think all the versions are already tagged in Github on every release, if that is your question? Thanks, Szehon On Thu, Jul 27, 2023 at 2:31 AM Brian Olsen <bitsondata...@gmail.com> wrote: > Thanks Fokko, > > Yeah, I think tío address that we would need to switch to a tagging that > prefixes the different project name as a namespace within the tags space > (e.g. pyIceberg-0.4.0, rust-0.0.1, etc…). But certainly this would result > in an explosion of tags as we continue to introduce more projects. I’m not > sure if this makes it difficult to find things as long as you start to > search the prefix in GitHub it should be easy enough to find. Has anyone > else worked on a project where this type of tagging is applied? Are their > any performance, searching, or other implications we are missing? > > Bits > > On Thu, Jul 27, 2023 at 4:18 AM Fokko Driesprong <fo...@apache.org> wrote: > >> 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 >>> >>
