Thanks for your response here Colin, > Perhaps there should be a "documentation" section in the KIP template?
I think that would do the trick. The nice idea behind formulating the section as "How to teach this?", is that it leaves it to the KIP author how to answer it. In most cases I would expect the section to be filled in like "We will update documentation section X and Y", but there might be cases where the answer is different (. I'm not going to die on this hill, and would be very happy with an added "Documentation" section if that option has more traction 👍 > the KIPs themselves are part of the documentation I understand this is how things currently work for many parts of Kafka documentation, but it's an idea I want to question and I am proposing to work to phase this out over time. KIPs are by definition documenting a proposed change. It is necessary to make assumptions about the current state of the Kafka code base at the time of writing, and those assumptions do not necessarily hold true at any arbitrary time later, when the KIP is being read. And I think this is what you are saying too, that for instance an implemented KIP that touches the protocol should also result in changes to the documentation. tl;dr; It's useful to also be able to read KIPs in hind-sight, but it shouldn't be required to do in-brain materialization of a series of KIPs to understand what the expected state of some feature currently is. What I am hoping with the proposed change to the KIP template is that there will be less chance for documentation to be an after-thought for new changes, and also for documentation changes to be scrutinized and reviewed during the KIP process, and that this will produce higher quality documentation over time. I'm curious if there are more opinions about this issue. BR, Anton Den tis 29 okt. 2024 kl 20:50 skrev Colin McCabe <cmcc...@apache.org>: > Hi Anton, > > Perhaps there should be a "documentation" section in the KIP template? > That might help raise awareness of the need to document these changes. > > I want to add, in the case of the wire protocol, the KIPs themselves are > part of the documentation. But they shouldn't be all of the documentation. > We should update protocol.html and possibly other docs in cases where we're > changing the protocol. I don't think it necessary needs to be done before > the change itself, but it should be done so that the release that includes > the protocol changes also includes their docs... > > best, > Colin > > > On Sat, Oct 26, 2024, at 10:53, Anton Agestam wrote: > > Hello Kafka devs 👋 > > > > Colin encouraged me in the 3.9.0 RC2 thread to contribute ideas around > how > > the protocol documentation can be improved. While I have concrete ideas > on > > this, the current biggest issue as I see it is that new changes are not > > making it into documentation, and there seems to be a bit of a general > lack > > of process with regards to this issue. > > > > KIP-893 was a very poignant example of this. It introduces a new concept > in > > the protocol's byte serialization format, none of which made it into > > documentation. This was extremely subtle and very time consuming to debug > > for me as an author of a third-party protocol implementation in Python > > that must remain compatible with Apache Kafka. Based on the view of the > > existing documentation, this flat out looked like a bug. > > > > The Python ecosystem solves this issue by requiring PEPs to have a "How > to > > teach this section", forcing documentation to not be an afterthought. I > am > > proposing to introduce the exact same concept for KIPs. I believe this > will > > be useful for all KIPs, not just those of the sort mentioned above. > > > > For changes to the protocol, I will also suggest that it should be > required > > for specification to be updated _before_ implementation changes are > merged, > > but this should perhaps be a separate discussion. > > > > Forcing us to include a plan for documentation in all future KIPs is > also a > > solid strategy to incrementally improve documentation over time. Kafka's > > docs are lacking also in other regards not related to the protocol. The > > proposed change will make sure we have a net positive development over > > time, towards a greater state of Kafka docs. > > > > Without first ensuring that there is a mechanism like this that makes > sure > > documentation does not rot over time, it doesn't seem like the best > > investment of time to improve documentation of the current state. For the > > continued success of Kafka this is highly important because it is what > > enables a thriving ecosystem. > > > > - Have there been something similar discussed previously? > > - What do you all think of this proposal? > > > > BR, > > Anton > > > > -- > > [image: Aiven] <https://www.aiven.io/> > > *Anton Agestam* (he/him or they/them) > > Software Engineer, *Aiven* > > anton.ages...@aiven.io | +46 704 486 289 > > aiven.io <https://www.aiven.io/> | > > <https://www.facebook.com/aivencloud> > > <https://www.linkedin.com/company/aiven/> < > https://twitter.com/aiven_io> >
