Good documentation is very important. The challenge is: What if a contributor is very skilled at writing code, but has trouble with documentation?
As Alan points out, if documentation becomes mandatory, we might lose skilled contributors. So we really need some kind of cooperation to help each other with this. I suggest: don't reject PRs that are missing documentation. Instead, let's try to organize Issues for each area of documentation that is needed and let's try outreach to attract technical writers to help close those Issues. On Thu, Nov 6, 2025 at 8:26 AM Sebastien Lorquet <[email protected]> wrote: > Hello > > Documentation is definitely important. And annoying. But important. > Without doc, as you said, new features stay in the dark and are not used. > > Maybe we can mandate basic addition of documentation for all new > features being added? > > > the nxinit subsystem had doc, a basic one, but a useful one. so it can > be done quite quickly. > > (btw, side note: when are these pull requests reopened?) > > Sebastien > > > On 11/6/25 13:42, Alan C. Assis wrote: > > Hi Everyone, > > > > I want to raise a question about Documentation. > > > > As everybody knows NuttX is missing Documentation for more than 90% of > the > > features it has. > > > > 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). > > > > So, I don't want to push so much, but on the other hand if I don't > request > > it, who will? And so NuttX will miss even more documentation. > > > > How can we handle situations like this: > > https://github.com/apache/nuttx/pull/17283 > > > > 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. > > > > 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). > > > > Please let me know what path NuttX should follow: Add Documentation or > > Ignore Documentation? > > > > BR, > > > > Alan > > >
