The current state of LLMs has made this a simple task and one of the best use cases. I get writing docs sucks, but I don't think that's much of a burden any more if the tools are applied.
On Wed, Apr 30, 2025 at 1:11 PM Josh McKenzie <jmcken...@apache.org> wrote: > This makes intuitive sense to me. > > In our case we could tie documentation to the process of promoting a > feature from “experimental” to production ready, though I fear that might > leave wiggle room for primary authors of some features to leave them as > experimental forever, not desiring to take on the burden of documenting > something that’s already merged in and usable by experts. > > Curious what others think. > > On Wed, Apr 30, 2025, at 12:10 PM, Miklosovic, Stefan via dev wrote: > > I am on OpenSearchCon and there was a discussion about the documentation > of features. In a nutshell, the policy they seem to have is that there are > some minimal requirements for documentation in place for each feature > introduced. That way, there is no way (or it is greatly minimised) that > there would be a feature released or some user-facing change introduced > without any documentation how to use it. > > > > Under the "documentation", in our case, I mean the docs which would end up > in cassandra.apache.org docs. > > > > In their case, the documentation is either part of the change or there is > a documentation issue (in GitHub terms) created which basically blocks the > release when not addressed. > > > > When there is no documentation about a feature or improvement, knob to > tweak etc, there is virtually nobody who knows about that except the > person who committed the code / people who participated in a review. I > think this is detrimental to the project. I do not see the point in > releasing something undocumented when the only people who know what is > going on are the ones who wrote it. > > > > If somebody argued that we have them in CHANGES.txt and NEWS.txt, neither > ends up on the website and I do not think they are appropriate vehicles for > user-facing documentation or for anything beyond few sentences. > > > > Could we introduce a policy which would require developers to introduce at > least minimal user-facing documentation (if applicable) before delivering > it / before releasing it and it would be part of the reviews? > > > > For now, while we also add documentation, I feel it is "the best-effort" > approach, it is not part of the official policy when delivering it. > > > > As of now, I can not see any information about documentation among "For > Code Contributions" points: > > > > > https://cwiki.apache.org/confluence/display/CASSANDRA/Cassandra+Project+Governance > > > > I am looking for adding there a new point: > > > > Code must not be committed when user-facing functionality is not > documented and visible without code inspection. > > > > Regards > > > > >
