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



Reply via email to