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
