bitsondatadev commented on PR #130: URL: https://github.com/apache/iceberg-rust/pull/130#issuecomment-1866632260
Update After having a meeting with Fokko and him showing me the [Arrow site documentation](https://arrow.apache.org/docs/) I am not totally opposed to the idea despite my long-winded blurb before. I think the crux of the decision lies with the simple argument for docs contributor experience. There's largely three models for docs that I've seen in open source where there are sub projects. 1. The docs are broken, out of sync, and out of date. 1. Docs are handled and maintained by a collective group of technical writers, developer experience engineers, and newcomers to the project that would benefit greatly from an aligned structure. 1. The core docs are handled by the collective "docs people" but sub projects are maintained by the project owners themselves. In my experience I've seen a lot of success from the second model and I tend to lean in that direction. This is because engineers have a nasty habit of not prioritizing docs as their time is stretched thin to contribute the code, and nobody wants to block code making it in to avoid the feature. However, there are a lot of unknown/silent features even living in Iceberg today that many are unaware of due to missing documentation. That said, I am impressed with the Arrow setup and would be interested to discuss a bit with their docs people to see how things are going from their perspective. I also would like to bring this up in a future community sync. If at the end of the day, you all maintain the rust docs well, and are happy to take on that focused role, then I'm not entirely against having us link the the Rust docs from the main Iceberg site and keep that more of a iceberg-rust contributor task as opposed to a collective Iceberg community task. Of course anyone in the Iceberg community can also easily work with mdbooks as well, and help contribute and we can just monitor if the docs start falling behind or missing a lot of feautres, then we may revisit the discussion at another time. Happy to hop on a call or even open up a mailing list discussion to dive in further. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: issues-unsubscr...@iceberg.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: issues-unsubscr...@iceberg.apache.org For additional commands, e-mail: issues-h...@iceberg.apache.org
