You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@nuttx.apache.org by "Alan C. Assis" <ac...@gmail.com> on 2025/11/06 12:42:26 UTC
To Document or NOT to Document
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
Re: To Document or NOT to Document
Posted by Matteo Golin <ma...@gmail.com>.
Hi,
I am in favour of rejecting (more often just waiting to merge) PRs without
docs. It makes our problem worse. It is also going to be extremely
difficult to find other people who are interested in technical doc writing,
primarily because they also need to be interested in reading and
understanding code to do so.
Michal is right in that for places where there are basically no docs yet,
asking a contributor to figure out what to include in their docs and where
to put them sucks for the contributor. In these cases I say we either:
- Suggest a file name/location for the contributor to use and just write
down something relevant about their feature so it can be used by others
- Have the contributor include this information in their PR somewhere and
then raise an issue to convert that into RST docs when an appropriate
section is made
Either way, that kind of generates more work for "us" but I don't see a way
around it. We're in this mess because we didn't enforce docs. If the
contributor is willing to create the necessary infrastructure for their
change's docs, that's even better.
If it's clear what docs are needed and where they should go, it's on the
contributor to do that. Nobody else will be more motivated to do it than
someone who has already spent a lot of time on their new feature. I'm
honestly surprised that people closed their PRs when asked to include docs,
that seems like a waste of their own time. I'm with Sebastian on this
though; if I don't understand a contribution well enough to use it, it
shouldn't be getting approved and merged anyways. Otherwise it's a useless
hidden feature of NuttX that we need to document later. Also consider that
there are many times where people make contributions and are told they
haven't done it the "right way" because other things haven't been
documented. This was the case for uORB
<https://github.com/apache/nuttx/pull/15573>, the GNSS lower-half
<https://github.com/apache/nuttx/pull/16605> and recently a CAN netdev
driver (at least this one had docs, just not accessible enough it seems,
https://github.com/apache/nuttx/pull/17161#issuecomment-3392199212). That's
incredibly frustrating for a new contributor. That is the real damage, not
rejecting PRs for lack of docs.
Mandatory inclusion of docs in the same PR as the change is already
included in our contributing guidelines (1.8) and was voted on. I'm not in
favour of a re-vote. I think that rule is the only way to solve this
problem which is driving away contributors and users. It's well within our
rights to reject PRs without docs. Javier is right, it's just as valuable
as source code.
As Michal pointed out though, there is now a bunch of missing documentation
that is "our responsibility" to write and get up to do date so that
contributors don't have as much burden in adding their own updates. I've
been working on the old text READMEs and added a standard template for
board documentation. I also tried to fill out a few application doc pages.
I think others need to do the same if we're going to get anywhere. A lot of
the applications and features have original authors we can find with git
blame, and maybe they'd be willing to write docs retroactively. As I
mentioned in the release planning, this needs to be fixed before 13.0.0 in
my opinion.
Matteo
On Thu, Nov 6, 2025, 10:04 AM Alan C. Assis <ac...@gmail.com> wrote:
> Wow, nice presentation!!!
>
> Thank you very much Javier. (Curious to know how he became a homeschool
> guy, in many countries it is not an option).
>
> Back to the topic: I agree with you, we need to make it clear in the
> Contributing guide that Documentation is required.
>
> If we have an agreement here I will ask for a vote and if approved I will
> update the Documentation accordingly.
>
> BR,
>
> Alan
>
>
> On Thu, Nov 6, 2025 at 11:44 AM Javier Alonso
> <ja...@geotab.com.invalid> wrote:
>
> > 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 <ac...@gmail.com> 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 <
> hartman.nathan@gmail.com
> > >
> > > 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 <
> sebastien@lorquet.fr
> > >
> > > > 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
> > > > > >
> > > > >
> > > >
> >
>
Re: To Document or NOT to Document
Posted by "Alan C. Assis" <ac...@gmail.com>.
Wow, nice presentation!!!
Thank you very much Javier. (Curious to know how he became a homeschool
guy, in many countries it is not an option).
Back to the topic: I agree with you, we need to make it clear in the
Contributing guide that Documentation is required.
If we have an agreement here I will ask for a vote and if approved I will
update the Documentation accordingly.
BR,
Alan
On Thu, Nov 6, 2025 at 11:44 AM Javier Alonso
<ja...@geotab.com.invalid> wrote:
> 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 <ac...@gmail.com> 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 <hartman.nathan@gmail.com
> >
> > 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 <sebastien@lorquet.fr
> >
> > > 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
> > > > >
> > > >
> > >
>
Re: To Document or NOT to Document
Posted by Javier Alonso <ja...@geotab.com.INVALID>.
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 <ac...@gmail.com> 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 <ha...@gmail.com>
> 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 <se...@lorquet.fr>
> > 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
> > > >
> > >
> >
Re: To Document or NOT to Document
Posted by "Alan C. Assis" <ac...@gmail.com>.
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 <ha...@gmail.com>
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 <se...@lorquet.fr>
> 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
> > >
> >
>
Re: To Document or NOT to Document
Posted by Sebastien Lorquet <se...@lorquet.fr>.
TBH this is a non problem. or one we should consider in favor of
dropping doc requirements.
PRs are reviewed. If a PR is missing doc, someone will see it and
request it. That will be an occasion to suggest some help if the
original submitter is unable to write doc.
I dont believe this will happen very often. Most of the time devs dont
write doc because no one requests it. If we start requesting doc, then
it will become a good practice and people will comply.
If I was more... grumpy, I could say that if the developer of a feature
is unable to document its own feature, then it's probably not a good
feature or well programmed.
In the industrial word, specification always come *before* the code, so
writing doc is not even an option.
hehe
Sebastien
On 11/6/25 15:04, Nathan Hartman 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 <se...@lorquet.fr>
> 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
>>>
Re: To Document or NOT to Document
Posted by "Alan C. Assis" <ac...@gmail.com>.
Hi Nathan,
Adding Issue to add Documentation later was my first approach, but it
doesn't work, because the Issue will keep open and nobody will take care of
it later.
So, we return to the initial problem: Do not request Documentation and
don't get Documentation.
BR,
Alan
On Thu, Nov 6, 2025 at 11:04 AM Nathan Hartman <ha...@gmail.com>
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 <se...@lorquet.fr>
> 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
> > >
> >
>
Re: To Document or NOT to Document
Posted by Nathan Hartman <ha...@gmail.com>.
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 <se...@lorquet.fr>
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
> >
>
Re: To Document or NOT to Document
Posted by Sebastien Lorquet <se...@lorquet.fr>.
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
>
Re: To Document or NOT to Document
Posted by "Alan C. Assis" <ac...@gmail.com>.
Hi Michal,
On Thu, Nov 6, 2025 at 10:13 AM Michal Lenc <mi...@seznam.cz> wrote:
> Hi Alan,
>
> > 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).
>
> I think it's the right approach that you push for the documentation and
> I completely agree with that.
>
> Regarding PR you linked (and I suppose it was my comment that triggered
> this thread), it's a bit more complicated in my opinion. CAN doesn't
> have a proper documentation right now, so API changes or new features
> are a bit harder to document. The contributor can't just change two
> sentences or add few lines describing the new ioctl, but he has to write
> the documentation basically from scratch.
>
>
I think incremental improvements are better than waiting for a well done
Documentation.
I think I maybe phrased my comment badly there, I am not against
> enhancing the documentation with new ioctl in that pull request, but I
> don't think we should require the committer to write the complete
> documentation about CAN interface (or all ioctls). It should be limited
> just to the newly added features and changes.
>
>
Don't worry about it. I understood your point and actually some months ago
we had a situation where a non frequent contributor (but he uses NuttX for
a long time already) submitted a commit and I requested to add
Documentation and he said: "ok, I will not submit my contribution". At that
moment I felt guilty, but I think it is better to have less features but
well documented features that everybody can use.
So, you just remembered to bring this discussion to here, this way we can
have an agreement about what to do in cases like this.
> 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.
>
> The only solution I see is to enhance the documentation so it's ready
> for the contributors. This way the developer will just look at the
> existing documentation and add few lines describing the new features he
> added. Yes, I know it means "we" have to write it, because no one will
> do that for us. I did some enhancements for ADC, DAC and few other
> peripherals some time ago, but there's still much work to do.
>
>
I think it is a chicken-egg dilemma: nobody improves the Documentation
because it is not good, but the Documentation is not good because nobody
improves it.
Everybody can do like you did, but if it is natural that people prefer to
contribute drivers/features than Documentation.
> > 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).
>
> I agree with your approach here. Honestly, I still think documentation
> change should come in the same merge request as the implementation
> itself. Or at least create to separate merge requests at the same time
> if we need it separately because of releases etc.
>
>
I understand that for some people documentation is more difficult to write
than code, because of the language barrier.
Maybe for Chinese people it is more difficult than for us Westerners. But
currently the translation tools are very good at doing the right
translation.
BR,
Alan
Re: To Document or NOT to Document
Posted by Michal Lenc <mi...@seznam.cz>.
Hi Alan,
> 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).
I think it's the right approach that you push for the documentation and
I completely agree with that.
Regarding PR you linked (and I suppose it was my comment that triggered
this thread), it's a bit more complicated in my opinion. CAN doesn't
have a proper documentation right now, so API changes or new features
are a bit harder to document. The contributor can't just change two
sentences or add few lines describing the new ioctl, but he has to write
the documentation basically from scratch.
I think I maybe phrased my comment badly there, I am not against
enhancing the documentation with new ioctl in that pull request, but I
don't think we should require the committer to write the complete
documentation about CAN interface (or all ioctls). It should be limited
just to the newly added features and changes.
> 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.
The only solution I see is to enhance the documentation so it's ready
for the contributors. This way the developer will just look at the
existing documentation and add few lines describing the new features he
added. Yes, I know it means "we" have to write it, because no one will
do that for us. I did some enhancements for ADC, DAC and few other
peripherals some time ago, but there's still much work to do.
> 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).
I agree with your approach here. Honestly, I still think documentation
change should come in the same merge request as the implementation
itself. Or at least create to separate merge requests at the same time
if we need it separately because of releases etc.
Michal
Re: To Document or NOT to Document
Posted by Tomek CEDRO <to...@cedro.info>.
TLDR:
* Contributing Guidelines already require documentation, everyone
should follow requirements no exceptions.
* Require at least minimalistic documentation.
* "Request Change" when PR needs more work, convert to Draft, stall, yes.
* Never solve existing problems by creating new problems!! :D :D
Hmm, we have documentation requirements in the Contributning
Gudelines, references below.
We did not define "where applicable" part true. But if a reviewer
requests for documentation that seems obvious it is applicable :D
If someone is willingly does not want to provide documentation, but
the functionality is valuable works and is not experimental, a
documentation stub should be at least provided with:
* new documentation page if it does not exist.
* mark TODO in the documentation (so we can find and fill missing parts later).
* description of the change only in the area touched by the code provided.
This really should not be a problem, does not require a lot additional
work from contributor, its a minimalistic requirement, but also sends
clear message that code needs documentation.
Documentation seems mandatory for breaking changes and new stuff which
seems obvious.
When "request changes" blocks merge and developer does not comply I
saw no project to merge such change until all problems are resolved.
We should not internally fight each other to enforce or push merges
behind back just to get things merged. People will get a clear message
that we require quality.
The old problem is quality or quantity? For me its quality.
The low contributions quality are constant subject. This propagates to
the overall project quality, like self-compatibility, but also
documentation. Guidelines were updated to face and fix the problem.
Things improved a bit recently. But there are still people who openly
violates this part (i.e. breaking changes). If we allow that nothing
will change. There was discussion about breaking changes, now its
discussion about documentation, probably new discussions will follow
soon.. while the clear requirements are already out there.
Following Contributing Guidelines is important. This is also about
culture of work and mutual respect. Engineers should document their
work. Very often documentation is more important than the result
because it allows recreating the result. Whoever worked with
"brilliant but undocumented" project will know the pain how much time
it takes to understand this "brilliant design" not to mention changing
anything over there :-)
Thanks :-)
Tomek
https://github.com/apache/nuttx/blob/master/CONTRIBUTING.md
https://github.com/apache/nuttx/blob/master/CONTRIBUTING.md#17-pr-requirements
1.7. PR requirements.
..
7. PR that introduces new feature must have Documentation included (see 1.8).
https://github.com/apache/nuttx/blob/master/CONTRIBUTING.md#18-documentation-requirements
1.8. Documentation requirements.
..
Changes must come with a documentation update (where applicable).
Documentation is part of the nuttx git repository. If code change is
part of nuttx-apps repository then separate PR in nuttx repository is
required. Otherwise documentation should come in the same PR as the
code update.
It is advised that the code and documentation should be split into two
separate commits in the same PR. This helps backporting and separates
possible code and documentation build errors. Squashing code together
with documentation into a single commit should be avoided, but is
acceptable.
If change presents new functionality documentation must be provided in
the same PR along with the code (not in the future).
If change requires existing documentation update it must be contained
in the same PR along with the code change (not in the future).
Successful documentation build logs (shortcut) are welcome.
This helps us keep documentation in sync with the code.
See:
https://github.com/apache/nuttx/tree/master/Documentation
https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
https://github.com/apache/nuttx/blob/master/CONTRIBUTING.md#113-breaking-changes-handling-process
1.13. Breaking changes handling process.
..
8. Change must be well documented (build / runtime test logs, pr, git
commit, documentation, release notes, etc) with clear notes on how to
fix the introduced problems.
On Thu, Nov 6, 2025 at 1:42 PM Alan C. Assis <ac...@gmail.com> 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
--
CeDeROM, SQ7MHZ, http://www.tomek.cedro.info