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 > > > > > > > > > > > > >
