Hi, issue with blank pages is already here: https://github.com/apache/nuttx/issues/11081
I haven't updated it for a long time, in fact I even forgot that I created it :) I agree with your diagnosis: better documentation means more contributors, and that's what NuttX needs. But the truth is that most devs hate writing documentation, especially if they're not native speakers. That's why we are where we are. It's far from perfect but it's getting better. On Wed, May 7, 2025, 14:10 Tomek CEDRO <to...@cedro.info> wrote: > Great work and Big Thank You Matteo! :-) > Tomek > > On Wed, May 7, 2025 at 4:51 AM Matteo Golin <matteo.go...@gmail.com> > wrote: > > > > Hello everyone, > > > > I just opened a PR here for migrating some of the README.txt files to > RST files (for board documentation, > > https://github.com/apache/nuttx/pull/16328). This is part of the long > list of old README files that need to be migrated, > > all laid out in issue #11077 ( > https://github.com/apache/nuttx/issues/11077). If you could help review > the PR (it's quite > > long and it only tackles 6 of the READMEs), that would be great. I plan > to continue migrating the remainder of these > > READMEs over the next few weeks. > > > > In case you haven't seen it, I've also added a tagging system to the > Nuttx documentation in this PR #16275 > > (https://github.com/apache/nuttx/pull/16275) and I've started adding > tags for chips in PR #16321 > > (https://github.com/apache/nuttx/pull/16321). This is part of an effort > to make the NuttX docs easier to search through > > (i.e. filter for supported boards that have some feature like `ethernet` > and also some chip `rp2040`, etc.). > > > > This is also part of the wider issue ( > https://github.com/apache/nuttx/issues/16278) to improve NuttX's quality > and > > reliability, specifically step #3. > > > > I have been working with an undergraduate engineering design team for > the past year on using NuttX for high powered > > rocketry. Most of the struggle I have seen students (myself included) > encounter are difficulties finding information > > about what NuttX supports or how to use some of the features, programs > or extend existing code to purpose-built > > applications. I really think NuttX could increase its user base (and > maintainer base) if some of this information was > > better documented and easier to find. To me, this is a bigger priority > than adding new features or even (in some cases) > > improving the stability of a few boards. If the documentation is clear > on what exactly is supported by NuttX, it would > > cause fewer headaches to people who select a board from the docs and > find out that the feature they expected does not > > work. As long as it's marked as unstable, we're being honest with the > user base and can work towards fixing it later. > > > > If I may, I have a suggestion that I think might help to improve the > quality of the documentation without requiring > > specifically assigned tasks: > > > > I've noticed that many of the maintainers on this mailing list have a > set of boards that are supported by NuttX, which > > as a whole covers a very large subset of the maintained NuttX boards. I > personally have mostly RP2040 based boards, but > > quite a few people I've noticed have STM32 boards. At this point, I > would assume that most of these board owners are > > very familiar with the process of tinkering with and uploading NuttX to > them (I know I've gotten *very* familiar with > > having to push BOOTSEL every time :) ). > > > > If everyone could take a little time to look at the documentation page > for the boards that they own, I think it would be > > very easy to identify improvements or missing information quickly. Then > we could all open a corresponding PR to make the > > updates. Since everyone has different boards, I think this would spread > the task fairly evenly, and the boards that are > > most common among all of us will get the most updates (probably a good > thing, they would maybe be the most common > > amongst users too). > > > > This goes for not just boards, but even examples you use often (I used > the `gpio` example recently and noticed that its > > documentation page is completely empty [ > https://nuttx.apache.org/docs/latest/applications/examples/gpio/index.html] > ). > > Same goes for drivers that are used often. There wasn't very much > documentation about the uORB framework until a few > > months ago when it started gaining some heavy use, and now that's a tool > I refer back to quite often. > > > > In summary, if there's something you use often and have become an expert > at, write down some of your expertise with it > > in the docs wherever it's missing and add a few of the relevant new > 'tags'. I think if we did that, the docs would > > improve massively in a relatively short period of time. > > > > If there's interest, I could also compile a list of empty documentation > pages (such as for the GPIO example) and make a > > checklist issue similar to #11077 just for tracking. Might be an easy > task for new contributors to tackle as well. > > > > -- > > Matteo Golin > > > > -- > CeDeROM, SQ7MHZ, http://www.tomek.cedro.info >
