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 > >
