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>
