Hi, I am in favour of rejecting (more often just waiting to merge) PRs without docs. It makes our problem worse. It is also going to be extremely difficult to find other people who are interested in technical doc writing, primarily because they also need to be interested in reading and understanding code to do so.
Michal is right in that for places where there are basically no docs yet, asking a contributor to figure out what to include in their docs and where to put them sucks for the contributor. In these cases I say we either: - Suggest a file name/location for the contributor to use and just write down something relevant about their feature so it can be used by others - Have the contributor include this information in their PR somewhere and then raise an issue to convert that into RST docs when an appropriate section is made Either way, that kind of generates more work for "us" but I don't see a way around it. We're in this mess because we didn't enforce docs. If the contributor is willing to create the necessary infrastructure for their change's docs, that's even better. If it's clear what docs are needed and where they should go, it's on the contributor to do that. Nobody else will be more motivated to do it than someone who has already spent a lot of time on their new feature. I'm honestly surprised that people closed their PRs when asked to include docs, that seems like a waste of their own time. I'm with Sebastian on this though; if I don't understand a contribution well enough to use it, it shouldn't be getting approved and merged anyways. Otherwise it's a useless hidden feature of NuttX that we need to document later. Also consider that there are many times where people make contributions and are told they haven't done it the "right way" because other things haven't been documented. This was the case for uORB <https://github.com/apache/nuttx/pull/15573>, the GNSS lower-half <https://github.com/apache/nuttx/pull/16605> and recently a CAN netdev driver (at least this one had docs, just not accessible enough it seems, https://github.com/apache/nuttx/pull/17161#issuecomment-3392199212). That's incredibly frustrating for a new contributor. That is the real damage, not rejecting PRs for lack of docs. Mandatory inclusion of docs in the same PR as the change is already included in our contributing guidelines (1.8) and was voted on. I'm not in favour of a re-vote. I think that rule is the only way to solve this problem which is driving away contributors and users. It's well within our rights to reject PRs without docs. Javier is right, it's just as valuable as source code. As Michal pointed out though, there is now a bunch of missing documentation that is "our responsibility" to write and get up to do date so that contributors don't have as much burden in adding their own updates. I've been working on the old text READMEs and added a standard template for board documentation. I also tried to fill out a few application doc pages. I think others need to do the same if we're going to get anywhere. A lot of the applications and features have original authors we can find with git blame, and maybe they'd be willing to write docs retroactively. As I mentioned in the release planning, this needs to be fixed before 13.0.0 in my opinion. Matteo On Thu, Nov 6, 2025, 10:04 AM Alan C. Assis <[email protected]> wrote: > Wow, nice presentation!!! > > Thank you very much Javier. (Curious to know how he became a homeschool > guy, in many countries it is not an option). > > Back to the topic: I agree with you, we need to make it clear in the > Contributing guide that Documentation is required. > > If we have an agreement here I will ask for a vote and if approved I will > update the Documentation accordingly. > > BR, > > Alan > > > On Thu, Nov 6, 2025 at 11:44 AM Javier Alonso > <[email protected]> wrote: > > > IMO, documentation should be a must since the very beginning. For > > long-running projects > > It's quite challenging when there's almost no documentation or when > > documentation wasn't a priority. > > to get the community to contribute and engage with documenting, as > > "it's not how we've been doing things". > > The only approach I see for this is to enforce documentation. > > > > A friend of mine has some awesome talks about this topic: Sebastián > > Ramírez, creator of FastAPI. He managed > > to make the project documentation-first and documentation-oriented. > > The sample code and the documentation > > itself is unit tested, so it's quite easy for rookies to get into the > > project, start learning, and developing. Here you > > have the keynote on EuroPython 2025, woth taking a look: > > https://www.youtube.com/watch?v=mwvmfl8nN_U > > > > My learnings from him and the community behind the scenes of FastAPI are: > > > > 1. If documentation is a priority, let your community know. > > 2. Take care of the documentation as if it were production code. > > 3. A project or feature can be as valuable as a diamond, but without > > proper documentation, it will go uncovered. > > 4. The portfolio of a project is mostly its documentation, the first > > interaction isn't usually the code but "how can I use it", or "does it > > fit my needs"? > > 5. Once the documentation is settled, every new contributor will > > unconciously work on it. > > > > > For reference, here you have FastAPI docs: > https://fastapi.tiangolo.com/ > > > > Javier Alonso (he, him, his) > > Geotab > > > > Team Lead - Embedded Systems | GEUR > > > > Javier Alonso (he, him, his) > > Geotab > > > > Team Lead - Embedded Systems | GEUR > > > > > > Quickly schedule a meeting > > > > Toll-free > > > > Visit > > > > +1 (877) 436-8221 > > www.geotab.com > > > > X | Facebook | YouTube | LinkedIn > > > > Celebrating 25 years of innovation and impact > > > > > > > > On Thu, Nov 6, 2025 at 3:27 PM Alan C. Assis <[email protected]> wrote: > > > > > > Just some ideas we could try to help our existing Documentation: > > > > > > Sony has nice Documentation and Tutorials: > > > > > > > https://developer.sony.com/spresense/development-guides/sdk_tutorials_en > > > > > > Since they never contributed it, maybe we can get it and include it on > > > NuttX Documentation because, but I don't know if it is illegal to do > it. > > > The best approach should be them doing it (we cannot get oranges from > our > > > neighbour's backyard, they should get and give us it). > > > > > > Also Xiaomi has some documentation that could cover some NuttX > features: > > > > > > https://doc.openvela.com/document?id=198&version=trunk&language=en > > > > > > BR, > > > > > > Alan > > > > > > On Thu, Nov 6, 2025 at 11:04 AM Nathan Hartman < > [email protected] > > > > > > wrote: > > > > > > > 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 > > > > > > > > > > > > > > > > > >
