Hi Michal, On Thu, Nov 6, 2025 at 10:13 AM Michal Lenc <[email protected]> wrote:
> 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 incremental improvements are better than waiting for a well done Documentation. 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. > > Don't worry about it. I understood your point and actually some months ago we had a situation where a non frequent contributor (but he uses NuttX for a long time already) submitted a commit and I requested to add Documentation and he said: "ok, I will not submit my contribution". At that moment I felt guilty, but I think it is better to have less features but well documented features that everybody can use. So, you just remembered to bring this discussion to here, this way we can have an agreement about what to do in cases like this. > 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. > > I think it is a chicken-egg dilemma: nobody improves the Documentation because it is not good, but the Documentation is not good because nobody improves it. Everybody can do like you did, but if it is natural that people prefer to contribute drivers/features than Documentation. > > 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. > > I understand that for some people documentation is more difficult to write than code, because of the language barrier. Maybe for Chinese people it is more difficult than for us Westerners. But currently the translation tools are very good at doing the right translation. BR, Alan
