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
signature.asc
Description: PGP signature
