Thanks Andrew, completely agree on scope and placement. My initial thought was to keep the Cookbook scoped to parquet-java to start with (e.g., encoding/decoding examples, schema changes, Bloom filters, dictionary handling, etc.), then potentially expand to other implementations if there’s interest.
Hosting it directly under parquet-java (perhaps as a `docs/cookbook` folder or Markdown guide linked from the README) may be the right first step. Once it matures, we could link it from the main Parquet site with a clear note about implementation specificity. Happy to start the effort if this sounds good to you and the community - Arnav On Tue, Oct 7, 2025 at 1:13 AM Andrew Lamb <[email protected]> wrote: > > - Whether a Parquet Cookbook would be valuable. > > I think so -- thank you for the suggestion > > As to what to include / where it should live, I think that partly depends > on what you are targeting > > If you are discussing parquet-java, the Apache Java implementation[1], then > I think the cookbook would belong in documentation associated with that > project (perhaps the javadocs or [3]?) > > Given that a common source of confusion is that people use the term > "Parquet" to mean parquet-java, which is one of several implementations[2], > I don't think parquet-java tutorials belong on the main > https://parquet.apache.org site unless it is very clear they are only for > one of the implementations. > > Andrew > > [1]: https://github.com/apache/parquet-java > [2]: https://parquet.apache.org/docs/overview/ > [3] https://github.com/apache/parquet-java?tab=readme-ov-file > > On Sun, Oct 5, 2025 at 7:51 AM Arnav Balyan <[email protected]> > wrote: > > > Hi all, > > > > I just wanted to start a discussion on Parquet documentation and get > > community feedback. > > > > Currently, the Parquet docs have gaps and appear outdated. There have > been > > user reports about unclear documentation (e.g., > > https://github.com/apache/parquet-java/issues/2914). > > > > One community suggestion is to introduce a Cookbook (thanks to Gang for > the > > great suggestion), similar to the one used by Apache Arrow: > > https://arrow.apache.org/cookbook > > > > The goal would be to provide simple, self-contained examples and guides > for > > Parquet users making it easier to adopt the format. > > > > Would love to hear feedback from the community on this, in particular: > > - Whether a Parquet Cookbook would be valuable. > > - Any examples or sections people would like to see included. > > - Suggestions for where the docs should live (eg - parquet.apache.org > vs. > > within the repo as markdown). > > > > Thanks, > > Arnav > > >
