My view from the "balcony" here: I think, some documentation is better that no documentation. If I would have to start in Cassandra right now, I would have a massive challenge. The project evolved a lot, documentation is not great, and the community is not the 20/30ish people of the past that where in slack most of the time.
Documentation helps people getting in the project and grow the community. Not everyone is open to get into slack and ask questions. From what I know, if someone votes against (of the committers) changes have to be done. And if documentation is a consideration, my concern is documentation would be on a couple of committers that would vote against? And if that person wouldn't vote, the feature could pass without proper docs? So, having some sort of rule would be an improvement? But I leave this to the people on the "dance floor" to decide. @Jon, @Patrick I've tested this with a driver PR from my team, and it works wonders! Cheers, Carlos ________________________________ From: Brandon Williams <dri...@gmail.com> Sent: 01 May 2025 15:51 To: dev@cassandra.apache.org <dev@cassandra.apache.org> Subject: Re: [DISCUSS] Requirement to document features before releasing them EXTERNAL EMAIL - USE CAUTION when clicking links or attachments On Thu, May 1, 2025 at 7:37 AM Benedict <bened...@apache.org<mailto:bened...@apache.org>> wrote: I am opposed to this. There’s too much imprecision in the “rule” while simultaneously being much too rigid, and it will be improperly enforced (we already have lots of rule breaking around modifying public APIs, that should have discuss threads and do not, for instance). This kind of arbitrary rule that is unaligned with contributors will likely lead to a bad and inconsistent documentation, which is worse than no documentation. I agree. This is too strong a measure. We have a documentation problem but trying to poorly litigate ourselves into fixing it isn't the best way. We could perhaps stipulate that for a feature to leave experimental status the community must vote and that documentation should be a consideration. But this will only capture big changes. We could perhaps try other ideas like moratoriums on contributions that are not documentation, to encourage improvements there. We could perhaps try having LLMs generate documentation that new contributors could take a first pass at editing for correctness, before a committer takes a final pass. I would support these ideas and others if we decide to try any of them out. I'm all for improving this situation. Kind Regards, Brandon
