Re: [DISCUSS] Require KIPs to include "How to teach this section"

2024-11-12 Thread Anton Agestam
Oh sorry for the noise all, I missed a couple subsequent responses that already addressed this. Den tis 12 nov. 2024 kl 16:05 skrev Anton Agestam : > Hi Matthias, > > Thanks for your input and for pointing that out. > > It at least is missing from this wiki page, and so is a link to the KIP > tem

Re: [DISCUSS] Require KIPs to include "How to teach this section"

2024-11-12 Thread Anton Agestam
Hi Matthias, Thanks for your input and for pointing that out. It at least is missing from this wiki page, and so is a link to the KIP template: https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=50859233#KafkaImprovementProposals-WhatshouldbeincludedinaKIP ? Perhaps there should be

Re: [DISCUSS] Require KIPs to include "How to teach this section"

2024-11-07 Thread Matthias J. Sax
It'a not a huge difference. Maybe just try it our yourself and click the link "Create KIP" in step (1) here: https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=50859233#KafkaImprovementProposals-Process It just uses the actual template to create a new wiki page, and opens it in e

Re: [DISCUSS] Require KIPs to include "How to teach this section"

2024-11-07 Thread Colin McCabe
Yeah, I agree, we should unify these! I'm not sure which of the paths you described are better. Is there any advantage to the "actual template" instead of the wiki page named template? The latter seems easier for me to understand, but maybe others feel differently? best, Colin On Thu, Nov 7,

Re: [DISCUSS] Require KIPs to include "How to teach this section"

2024-11-07 Thread Matthias J. Sax
Oh I see... The link actually goes to a "template" (this is wiki feature), while there is also a "KIP Template" wiki page (https://cwiki.apache.org/confluence/display/KAFKA/KIP-Template) -- this is not a "template" but just a regular wiki page... Sounds like a split brain problem... We have

Re: [DISCUSS] Require KIPs to include "How to teach this section"

2024-11-06 Thread Sophie Blee-Goldman
It seems like the "Create KIP" button on the main KIP page actually does not point to this template? I was actually surprised to hear that we had a "Documentation Plan" section already because I have literally never seen it. I took a quick look at this button but as far as I can tell it's pointing

Re: [DISCUSS] Require KIPs to include "How to teach this section"

2024-11-04 Thread Greg Harris
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, a

Re: [DISCUSS] Require KIPs to include "How to teach this section"

2024-11-04 Thread Matthias J. Sax
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 w

Re: [DISCUSS] Require KIPs to include "How to teach this section"

2024-11-04 Thread Colin McCabe
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, Coli

Re: [DISCUSS] Require KIPs to include "How to teach this section"

2024-11-01 Thread Matthias J. Sax
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,

Re: [DISCUSS] Require KIPs to include "How to teach this section"

2024-11-01 Thread Colin McCabe
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

Re: [DISCUSS] Require KIPs to include "How to teach this section"

2024-11-01 Thread Claude Warren, Jr
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. I can see cases where the change is not visible

Re: [DISCUSS] Require KIPs to include "How to teach this section"

2024-10-31 Thread Anton Agestam
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 expe

Re: [DISCUSS] Require KIPs to include "How to teach this section"

2024-10-29 Thread Colin McCabe
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 documentat

[DISCUSS] Require KIPs to include "How to teach this section"

2024-10-26 Thread Anton Agestam
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