I love the idea of having great docs, but blocking at this point probably hurts the project more than it helps. How about we see if we can find people that are actually interested in working on them? Figuring that out needs to happen regardless. I suspect not many of us want to, or have time to.
Let's also be realistic - money is also a factor here. There's 2 groups of us: * Full timers require employers willing to contribute people's time towards doc writing. * For independent folks like myself: getting someone to sponsor our time contributing docs It is *unreasonable* to expect people to donate massive amounts of free time towards doc writing if they can't get compensated for it somehow. Personally, I already spend enough of my time working, I am not interested in adding more to my plate, especially when I don't particularly enjoy it. I like code and understanding how stuff works. So we should solve the who and how problems, before we put up roadblocks. Once we have a steady stream of contributions we can work out if we want to block releases on them. Hopefully we wont have to. So.. who *wants* to write docs? Jon On Thu, May 1, 2025 at 6:52 AM Brandon Williams <dri...@gmail.com> wrote: > On Thu, May 1, 2025 at 7:37 AM Benedict <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 > >
