Hey Gurudatt, Thanks for the great feedback! Comments inlined...
On Wed, Nov 13, 2019 at 10:57 PM Gurudatt Kulkarni <[email protected]> wrote: > Hi Ethan, > > Thanks for the RFC. I have a few observations about the docs. I saw the > diagram for the docs, asf-site and master are kept as separate branches, > currently. > > (1) I suggest two approaches for maintaining the docs looking at how other > popular Apache projects do, > > - Apache Flink <https://github.com/apache/flink/tree/master/docs> - > Keeping docs part of the master. > > > - Keeping docs part of the master will help in updating the docs and > code simultaneously when the releases are cut. (I prefer this). > > Agree. I also suggest putting docs along with the code on master in the RFC. > > - Apache Kafka <https://github.com/apache/kafka-site> - Keeping a > separate repository for documentation. > > > - A separate repo will give much more flexibility and independence in > terms of deployment, but will also be a bit inconvenient in terms of > switching between the repository while making changes, like the > current > case of different branches. I can't think of any other > advantages of doing > this. > Yeah, in the current RFC I suggest maintaining the site-level documentation (more of high-level information, not specific to a release) in the asf-site branch as what we have now, to continue the tradition. Yet I'm also fine with a separate repo for maintaining the documentation site. Apache Spark uses this approach as well (https://github.com/apache/spark-website). @vinoth wdyt? > > > (2) Introduce a new section for listing PMC members and Committers - > > This will help in getting in touch with core contributors and give them > visibility as well. > > Good idea. Can we have this in the "Community" page? > > (3) For improving new contributor experience, > > Add a little more detail regarding the project structure and what each > module is designed for. A section on describing the Hudi metadata structure > (A good reference https://kafka.apache.org/protocol) > > Yes, this is handy. We can also explain the information of Hudi metadata structure in the user documentation. > > (4) Regarding the comparison table with other alternatives > > Not sure if we should keep this. Since all projects are developing at a > good pace, keeping tabs on what each project is doing or has implemented > can be taxing, since people here are majorly working on Hudi. It shouldn't > happen that we present a misleading or old comparison regarding the > features of other projects. I feel benchmarks and comparisons make a good > topic for blog posts since they are always dated. > Agree that the comparison can get outdated if not updated frequently. So may be add the time when the comparison is done (either in blog or a separate page), e.g., "as of Nov 2019"? I think it's still beneficial even for ourselves to compare Hudi with other solutions periodically so we prioritize our work based on the state of the art and keep Hudi relevant in the ecosystem. Users may want to use this comparison to choose among Hudi and others. Maybe we can update the comparison every Hudi release (a month or two) or quarter? > Regards, > Gurudatt > > > On Thu, Nov 14, 2019 at 6:21 AM Y Ethan Guo <[email protected]> > wrote: > > > Hey folks, > > > > I put my thoughts around the topic in this RFC: > > > > RFC-10: Restructuring and auto-generation of docs > > > > > https://cwiki.apache.org/confluence/display/HUDI/RFC-10%3A+Restructuring+and+auto-generation+of+docs > > > > Feel free to provide feedback there or here. > > > > Thanks, > > - Ethan > > >
