Enhancing documentation

[Matteo Golin <ma...@gmail.com>]

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

Re: Enhancing documentation

[Matteo Golin <ma...@gmail.com>]

Yes, that makes perfect sense. Thanks for linking the issue!

Wonder if we could game-ify some of these issues somehow, or make it more
appealing to have docs written. I know guidelines for everything going
forward requires docs to be included, but some way of motivating patches
for existing gaps would be helpful. I'll think on it, but in any case I'm
happy to continue fixing some of these gaps as best I can!

Matteo

On Fri, May 9, 2025, 3:14 PM raiden00pl <ra...@gmail.com> wrote:

> 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 <ma...@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
> >
>

Re: Enhancing documentation

[raiden00pl <ra...@gmail.com>]

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 <ma...@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
>

Re: Enhancing documentation

[Matteo Golin <ma...@gmail.com>]

I've opened a draft PR here creating a standardized template for board documentation: https://github.com/apache/nuttx/pull/16405

Please take a look and leave your suggestions for what should be included in a board documentation page so that we can
start using this template to enhance quality and consistency!

Best,
-- 
Matteo Golin

Re: Enhancing documentation

[Tomek CEDRO <to...@cedro.info>]

Great work and Big Thank You Matteo! :-)
Tomek

On Wed, May 7, 2025 at 4:51 AM Matteo Golin <ma...@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