Hi all, FYI the Documentation Plan was added to the template in September 2023 around the time ~979 was opened. I was not able to find any contemporary discussion thread, does anyone know of where/when we discussed this change? Not to say that I think the change to the template should be undone, as I think it is very important that we write good documentation for our features, and encourage this by changing our processes.
I think "how to teach the KIP's concepts" is more appealing to me than the template's current wording of "List affected areas/files". KIPs could also contain the first iteration of the user-facing documentation, either an outline of topics that need to be documented, or text that can later be directly promoted to a documentation page for sufficiently small changes. I also support moving away from our current practice of pointing users to KIPs for first- or second-level documentation, because they are written for contributors & committers, not end users. As part of enforcing this practice, when reviewing KIP PRs, we could look for places where the KIP is linked/mentioned and determine if a purpose-written piece of documentation would be more appropriate. Thanks, Greg On Mon, Nov 4, 2024 at 11:10 AM Matthias J. Sax <mj...@apache.org> wrote: > Guess it would be better to use the template when starting a new KIP -- > that's why we have it :) > > On 11/4/24 10:23 AM, Colin McCabe wrote: > > Hi Matthias, > > > > Thanks for pointing this out! Maybe what we need is to start enforcing > that this section appears (even if it just says "no change"). I think we > have people copying previous KIPs (including me...) and in that case just > we won't have the section, unless someone complains. > > > > best, > > Colin > > > > > > On Fri, Nov 1, 2024, at 19:10, Matthias J. Sax wrote: > >> The KIP already has a section "Documentation Plan" > >> > >> > https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=50859709#KIPTemplate-DocumentationPlan > >> > >> If it's not used properly, committers reviewing (and voting) KIPs must > >> be reminded to pay more attention and emphasis on good documentation, > >> and also make sure the PRs contains corresponding doc updates... > >> > >> Overall, I agree and support to pay attention to good docs. I just don't > >> see that we need to change anything in the "official process" -- we just > >> need to change our behavior and stick to the exiting process? > >> > >> > >> -Matthias > >> > >> On 11/1/24 2:50 PM, Colin McCabe wrote: > >>> On Fri, Nov 1, 2024, at 07:08, Claude Warren, Jr wrote: > >>>> I like this idea. I'm not sure what the section should be called but > It > >>>> should spell out what changes from a customer (I don't like the term > user, > >>>> drug dealers have users -- we should have customers) point of view > and from > >>>> a developer point of view. > >>> > >>> Hi Claude, > >>> > >>> Sorry to nitpick, but I think "user" really is the correct term. > Apache Kafka is an open source project. We do not have "customers" because > we're not a business. Indeed, users should feel free to contribute to Kafka > and not view it as a vendor / customer relationship. > >>> > >>> Of course, if you want a vendor / customer relationship, there are > lots of companies in the ecosystem that can provide that. But the open > source project should be a collaboration. I think most of us wear both > "user" and "developer" hats, and that's a good thing. > >>> > >>>> > >>>> I can see cases where the change is not visible to the customer but > impacts > >>>> how developers interact with the system. I can also see cases where > the > >>>> change is almost 100% customer focused with little change to the > developers > >>>> perception. > >>>> > >>>> Whatever changes are noted in the section should be accounted for in > the PR > >>>> before it is accepted. Keeping in mind that as the change evolves > through > >>>> testing to documentation requirements may change too. > >>>> > >>>> I think we need more focus on documenting how to use and configure > kafka in > >>>> various environments, but I also perceive that we do not have the > people to > >>>> do that, so let's at least collect the information in some reasonable > form. > >>>> > >>> > >>> Many changes involve multiple PRs. I think documentation is no > different than any other aspect of a feature or change. It can be done > incrementally if necessary. Hopefully having the section in the KIP would > help remind us to do it, though! And motivate discussion about what kind of > documentation would be best. > >>> > >>> best, > >>> Colin > >>> > >>>> Claude > >>>> > >>>> On Thu, Oct 31, 2024 at 12:21 PM Anton Agestam > >>>> <anton.ages...@aiven.io.invalid> wrote: > >>>> > >>>>> 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> > >>>>>> > >>>>> >
