Hi Alan,
So, in order to improve it when someone adds a new feature or modifies
something related to that feature I request to add or improve the existing
Documentation.
But we know that normally Developers don't want to write Documentation
(normally also don't know how to write a good Documentation).
I think it's the right approach that you push for the documentation and
I completely agree with that.
Regarding PR you linked (and I suppose it was my comment that triggered
this thread), it's a bit more complicated in my opinion. CAN doesn't
have a proper documentation right now, so API changes or new features
are a bit harder to document. The contributor can't just change two
sentences or add few lines describing the new ioctl, but he has to write
the documentation basically from scratch.
I think I maybe phrased my comment badly there, I am not against
enhancing the documentation with new ioctl in that pull request, but I
don't think we should require the committer to write the complete
documentation about CAN interface (or all ioctls). It should be limited
just to the newly added features and changes.
How can we fix the existing problem without creating a new one (developers
deciding to avoid contributing because they don't want to write
Documentation)? I don't know how other projects like FreeRTOS and Zephyr
handle it.
The only solution I see is to enhance the documentation so it's ready
for the contributors. This way the developer will just look at the
existing documentation and add few lines describing the new features he
added. Yes, I know it means "we" have to write it, because no one will
do that for us. I did some enhancements for ADC, DAC and few other
peripherals some time ago, but there's still much work to do.
Recently I asked the contributor from Xiaomi to add Documentation for an
important new subsystem (ClockDevice) and after he said will do it later I
converted the PR to Draft to avoid the Documentation never coming (if you
look at Issues you will find a lot of false promises about Documentation
coming later).
I agree with your approach here. Honestly, I still think documentation
change should come in the same merge request as the implementation
itself. Or at least create to separate merge requests at the same time
if we need it separately because of releases etc.
Michal
