Our nodetool pages can definitely be improved. Each has a bare sentence description.
I mean what can a newcomer do with "gossipinfo - Shows the gossip information for the cluster" An example of where any extra denseness, in this case examples of when and why, would go a long way. On Wed, 30 Apr 2025 at 22:39, Miklosovic, Stefan via dev < dev@cassandra.apache.org> wrote: > > > To extend the first e-mail to cover the practicalities: > > > > 1. changes introduced to nodetool would not be part of this because > they are self-documented (docs of help is autogenerated) > 2. introduction of changes into cassandra.yaml is already covered as > that is what is autogenerated / on website also. > 3. Applying common sense, if it is just enough to mention in NEWS.txt, > that is also fine. > 4. metrics - I bet there are some which are not documented, we should > find a way how to autogenerate them into the website. > > > > I am also to blame and showing I am not a hypocrite, I have never > delivered in-depth user documentation of CEP-24 with examples, use cases, > and so on. I am trying to be more aware of the documentation when > delivering features, to raise awareness about that etc. It is easy to not > think about this too much when developers are in a rush and similar. If > there was a hard requirement for the documentation, I would do it right > away and I would not need to deal with this now. > > > > I understand that when delivering heavy-weights like CEP-15 we can not > expect that all the docs will be done upon delivery but I want to stress > the fact that providing usable documentation should be definitely something > to think about when releasing it. Same goes for all other non-trivial > features. > > > > > > *From: *Josh McKenzie <jmcken...@apache.org> > *Date: *Wednesday, 30 April 2025 at 22:11 > *To: *dev <dev@cassandra.apache.org> > *Cc: *Miklosovic, Stefan <stefan.mikloso...@netapp.com> > *Subject: *Re: [DISCUSS] Requirement to document features before > releasing them > > *EXTERNAL EMAIL - USE CAUTION when clicking links or attachments * > > > > 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 > <https://urldefense.com/v3/__http:/cassandra.apache.org__;!!Nhn8V6BzJA!Q2uU9Ab38CiJSRJuSPI9bIKJfTgR9yuneyK2LGgK4a4YNMwL2jD1yVsG018wQlMrMAgKI9CfFzOtXbLNjERRjfVMrw$> > 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 > <https://urldefense.com/v3/__https:/cwiki.apache.org/confluence/display/CASSANDRA/Cassandra*Project*Governance__;Kys!!Nhn8V6BzJA!Q2uU9Ab38CiJSRJuSPI9bIKJfTgR9yuneyK2LGgK4a4YNMwL2jD1yVsG018wQlMrMAgKI9CfFzOtXbLNjETp4KSISQ$> > > > > 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 > > > > >
