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