[VOTE] Features contributions should include Documentation

["Alan C. Assis" <ac...@gmail.com>]

As discussed in [1] we need to improve our Documentation and requesting
Documentation from the author of the new added Features seems to be the
best approach.

So these are the proposals to be voted:

- Anyone submitting a new features should write Documentation to it, which
he/she is the author is knows more about that features than other people
and could write better Documentation;

- Anyone adding a new function (or a new resource such as ioctl, etc)
should include it in the existing Documentation; If there is not
Documentation for that Feature/Driver/whatever, then the Reviews should
suggest the contributor to submit a basic page (without forcing him to do
it)

I think these are the key points collected from the previous discussion.

BR,

Alan

1 - https://lists.apache.org/thread/5dklb9r2k9vpl9jwpromdn0lcv3h0985

Re: [VOTE] Features contributions should include Documentation

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

That makes sense. I always interpreted that as telling possible
contributors that they can submit PRs as simple as typo fixes. I agree that
the website and MD file should be the same. Maybe a hyperlink is easiest.

Matteo

On Thu, Nov 6, 2025, 4:08 PM Tomek CEDRO <to...@cedro.info> wrote:

> Thanks Alan, yes docs should reflect Contributing Guidelines 1:1 maybe
> a dedicated page for easier maintenance? :-)
>
> On Thu, Nov 6, 2025 at 10:00 PM Alan C. Assis <ac...@gmail.com> wrote:
> >
> > Yes, I think you and Matteo are right, the CONTRIBUTING.md makes it
> clean,
> > but the online Contributing Documentation doesn't:
> >
> > https://nuttx.apache.org/docs/latest/contributing/documentation.html
> >
> > "Contributions to documentation are appreciated. These can be as simple
> as
> > fixing a typo or formatting issues to more involved changes such as
> > documenting parts of NuttX which are not yet covered or even writing
> guides
> > for other users."
> >
> > So, is it "appreciated or required" ? :-D
> >
> > I think "we have a problem", there is not a single point of truth, we
> have
> > information spread all over the places and conflicting.
> >
> > After voting, let's make the online Contributing Documentation reflecting
> > CONTRIBUTING.md and the definitions included here.
> >
> > BR,
> >
> > Alan
> >
> > On Thu, Nov 6, 2025 at 5:47 PM Tomek CEDRO <to...@cedro.info> wrote:
> >
> > > Alan we already have Documentation Requirements in the Contributing
> > > Guidelines [1]. What we are exactly voting for and what is the
> > > intended voting outcome / action?
> > > Tomek
> > >
> > > 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
> > >
> > > [1]
> > >
> https://github.com/apache/nuttx/blob/master/CONTRIBUTING.md#18-documentation-requirements
> > >
> > > On Thu, Nov 6, 2025 at 8:59 PM Alan C. Assis <ac...@gmail.com>
> wrote:
> > > >
> > > > As discussed in [1] we need to improve our Documentation and
> requesting
> > > > Documentation from the author of the new added Features seems to be
> the
> > > > best approach.
> > > >
> > > > So these are the proposals to be voted:
> > > >
> > > > - Anyone submitting a new features should write Documentation to it,
> > > which
> > > > he/she is the author is knows more about that features than other
> people
> > > > and could write better Documentation;
> > > >
> > > > - Anyone adding a new function (or a new resource such as ioctl, etc)
> > > > should include it in the existing Documentation; If there is not
> > > > Documentation for that Feature/Driver/whatever, then the Reviews
> should
> > > > suggest the contributor to submit a basic page (without forcing him
> to do
> > > > it)
> > > >
> > > > I think these are the key points collected from the previous
> discussion.
> > > >
> > > > BR,
> > > >
> > > > Alan
> > > >
> > > > 1 - https://lists.apache.org/thread/5dklb9r2k9vpl9jwpromdn0lcv3h0985
> > >
> > >
> > >
> > > --
> > > CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
> > >
>
>
>
> --
> CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
>

Re: [VOTE] Features contributions should include Documentation

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

Thanks Alan, yes docs should reflect Contributing Guidelines 1:1 maybe
a dedicated page for easier maintenance? :-)

On Thu, Nov 6, 2025 at 10:00 PM Alan C. Assis <ac...@gmail.com> wrote:
>
> Yes, I think you and Matteo are right, the CONTRIBUTING.md makes it clean,
> but the online Contributing Documentation doesn't:
>
> https://nuttx.apache.org/docs/latest/contributing/documentation.html
>
> "Contributions to documentation are appreciated. These can be as simple as
> fixing a typo or formatting issues to more involved changes such as
> documenting parts of NuttX which are not yet covered or even writing guides
> for other users."
>
> So, is it "appreciated or required" ? :-D
>
> I think "we have a problem", there is not a single point of truth, we have
> information spread all over the places and conflicting.
>
> After voting, let's make the online Contributing Documentation reflecting
> CONTRIBUTING.md and the definitions included here.
>
> BR,
>
> Alan
>
> On Thu, Nov 6, 2025 at 5:47 PM Tomek CEDRO <to...@cedro.info> wrote:
>
> > Alan we already have Documentation Requirements in the Contributing
> > Guidelines [1]. What we are exactly voting for and what is the
> > intended voting outcome / action?
> > Tomek
> >
> > 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
> >
> > [1]
> > https://github.com/apache/nuttx/blob/master/CONTRIBUTING.md#18-documentation-requirements
> >
> > On Thu, Nov 6, 2025 at 8:59 PM Alan C. Assis <ac...@gmail.com> wrote:
> > >
> > > As discussed in [1] we need to improve our Documentation and requesting
> > > Documentation from the author of the new added Features seems to be the
> > > best approach.
> > >
> > > So these are the proposals to be voted:
> > >
> > > - Anyone submitting a new features should write Documentation to it,
> > which
> > > he/she is the author is knows more about that features than other people
> > > and could write better Documentation;
> > >
> > > - Anyone adding a new function (or a new resource such as ioctl, etc)
> > > should include it in the existing Documentation; If there is not
> > > Documentation for that Feature/Driver/whatever, then the Reviews should
> > > suggest the contributor to submit a basic page (without forcing him to do
> > > it)
> > >
> > > I think these are the key points collected from the previous discussion.
> > >
> > > BR,
> > >
> > > Alan
> > >
> > > 1 - https://lists.apache.org/thread/5dklb9r2k9vpl9jwpromdn0lcv3h0985
> >
> >
> >
> > --
> > CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
> >



-- 
CeDeROM, SQ7MHZ, http://www.tomek.cedro.info

Re: [VOTE] Features contributions should include Documentation

["Alan C. Assis" <ac...@gmail.com>]

Yes, I think you and Matteo are right, the CONTRIBUTING.md makes it clean,
but the online Contributing Documentation doesn't:

https://nuttx.apache.org/docs/latest/contributing/documentation.html

"Contributions to documentation are appreciated. These can be as simple as
fixing a typo or formatting issues to more involved changes such as
documenting parts of NuttX which are not yet covered or even writing guides
for other users."

So, is it "appreciated or required" ? :-D

I think "we have a problem", there is not a single point of truth, we have
information spread all over the places and conflicting.

After voting, let's make the online Contributing Documentation reflecting
CONTRIBUTING.md and the definitions included here.

BR,

Alan

On Thu, Nov 6, 2025 at 5:47 PM Tomek CEDRO <to...@cedro.info> wrote:

> Alan we already have Documentation Requirements in the Contributing
> Guidelines [1]. What we are exactly voting for and what is the
> intended voting outcome / action?
> Tomek
>
> 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
>
> [1]
> https://github.com/apache/nuttx/blob/master/CONTRIBUTING.md#18-documentation-requirements
>
> On Thu, Nov 6, 2025 at 8:59 PM Alan C. Assis <ac...@gmail.com> wrote:
> >
> > As discussed in [1] we need to improve our Documentation and requesting
> > Documentation from the author of the new added Features seems to be the
> > best approach.
> >
> > So these are the proposals to be voted:
> >
> > - Anyone submitting a new features should write Documentation to it,
> which
> > he/she is the author is knows more about that features than other people
> > and could write better Documentation;
> >
> > - Anyone adding a new function (or a new resource such as ioctl, etc)
> > should include it in the existing Documentation; If there is not
> > Documentation for that Feature/Driver/whatever, then the Reviews should
> > suggest the contributor to submit a basic page (without forcing him to do
> > it)
> >
> > I think these are the key points collected from the previous discussion.
> >
> > BR,
> >
> > Alan
> >
> > 1 - https://lists.apache.org/thread/5dklb9r2k9vpl9jwpromdn0lcv3h0985
>
>
>
> --
> CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
>

Re: [VOTE] Features contributions should include Documentation

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

Alan we already have Documentation Requirements in the Contributing
Guidelines [1]. What we are exactly voting for and what is the
intended voting outcome / action?
Tomek

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

[1] https://github.com/apache/nuttx/blob/master/CONTRIBUTING.md#18-documentation-requirements

On Thu, Nov 6, 2025 at 8:59 PM Alan C. Assis <ac...@gmail.com> wrote:
>
> As discussed in [1] we need to improve our Documentation and requesting
> Documentation from the author of the new added Features seems to be the
> best approach.
>
> So these are the proposals to be voted:
>
> - Anyone submitting a new features should write Documentation to it, which
> he/she is the author is knows more about that features than other people
> and could write better Documentation;
>
> - Anyone adding a new function (or a new resource such as ioctl, etc)
> should include it in the existing Documentation; If there is not
> Documentation for that Feature/Driver/whatever, then the Reviews should
> suggest the contributor to submit a basic page (without forcing him to do
> it)
>
> I think these are the key points collected from the previous discussion.
>
> BR,
>
> Alan
>
> 1 - https://lists.apache.org/thread/5dklb9r2k9vpl9jwpromdn0lcv3h0985



-- 
CeDeROM, SQ7MHZ, http://www.tomek.cedro.info

Re: [VOTE] Features contributions should include Documentation

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

+1 but this is already in our contribution guidelines.

On Thu, Nov 6, 2025 at 2:59 PM Alan C. Assis <ac...@gmail.com> wrote:

> As discussed in [1] we need to improve our Documentation and requesting
> Documentation from the author of the new added Features seems to be the
> best approach.
>
> So these are the proposals to be voted:
>
> - Anyone submitting a new features should write Documentation to it, which
> he/she is the author is knows more about that features than other people
> and could write better Documentation;
>
> - Anyone adding a new function (or a new resource such as ioctl, etc)
> should include it in the existing Documentation; If there is not
> Documentation for that Feature/Driver/whatever, then the Reviews should
> suggest the contributor to submit a basic page (without forcing him to do
> it)
>
> I think these are the key points collected from the previous discussion.
>
> BR,
>
> Alan
>
> 1 - https://lists.apache.org/thread/5dklb9r2k9vpl9jwpromdn0lcv3h0985
>

Re: [VOTE] Features contributions should include Documentation

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

> Btw, perhaps we could summarize what documentation pages we are missing.
> GitHub issue would be the best place for this?

The issue with blank pages is here:
https://github.com/apache/nuttx/issues/11081

We probably need a similar issue with pages that need improvement.
Or we could create a separate issue for each not complete page for better
visibility.

The rest of the issues related to documentation can be easily accessed with
the
"Area: Documentation" label:
https://github.com/apache/nuttx/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Area%3A%20Documentation%22


pt., 7 lis 2025 o 12:50 Alan C. Assis <ac...@gmail.com> napisał(a):

> Yes, that is a good idea, I remember Mateusz did it during the process to
> migrate Confluence pages to Doc RST.
>
> This way we can track which pages still need to be created.
>
> If you look at
> https://nuttx.apache.org/docs/latest/applications/index.html
> you will see almost all apps have pages, but almost all are empty pages.
>
> BR,
>
> Alan
>
> On Fri, Nov 7, 2025 at 6:25 AM Michal Lenc <mi...@seznam.cz> wrote:
>
> > +1 for this, I think the wording of these points is a good compromise.
> >
> > Btw, perhaps we could summarize what documentation pages we are missing.
> > GitHub issue would be the best place for this?
> >
> > Michal
> >
> > On 11/6/25 20:58, Alan C. Assis wrote:
> > > As discussed in [1] we need to improve our Documentation and requesting
> > > Documentation from the author of the new added Features seems to be the
> > > best approach.
> > >
> > > So these are the proposals to be voted:
> > >
> > > - Anyone submitting a new features should write Documentation to it,
> > which
> > > he/she is the author is knows more about that features than other
> people
> > > and could write better Documentation;
> > >
> > > - Anyone adding a new function (or a new resource such as ioctl, etc)
> > > should include it in the existing Documentation; If there is not
> > > Documentation for that Feature/Driver/whatever, then the Reviews should
> > > suggest the contributor to submit a basic page (without forcing him to
> do
> > > it)
> > >
> > > I think these are the key points collected from the previous
> discussion.
> > >
> > > BR,
> > >
> > > Alan
> > >
> > > 1 - https://lists.apache.org/thread/5dklb9r2k9vpl9jwpromdn0lcv3h0985
> > >
> >
> >
>

Re: [VOTE] Features contributions should include Documentation

["Alan C. Assis" <ac...@gmail.com>]

Yes, that is a good idea, I remember Mateusz did it during the process to
migrate Confluence pages to Doc RST.

This way we can track which pages still need to be created.

If you look at https://nuttx.apache.org/docs/latest/applications/index.html
you will see almost all apps have pages, but almost all are empty pages.

BR,

Alan

On Fri, Nov 7, 2025 at 6:25 AM Michal Lenc <mi...@seznam.cz> wrote:

> +1 for this, I think the wording of these points is a good compromise.
>
> Btw, perhaps we could summarize what documentation pages we are missing.
> GitHub issue would be the best place for this?
>
> Michal
>
> On 11/6/25 20:58, Alan C. Assis wrote:
> > As discussed in [1] we need to improve our Documentation and requesting
> > Documentation from the author of the new added Features seems to be the
> > best approach.
> >
> > So these are the proposals to be voted:
> >
> > - Anyone submitting a new features should write Documentation to it,
> which
> > he/she is the author is knows more about that features than other people
> > and could write better Documentation;
> >
> > - Anyone adding a new function (or a new resource such as ioctl, etc)
> > should include it in the existing Documentation; If there is not
> > Documentation for that Feature/Driver/whatever, then the Reviews should
> > suggest the contributor to submit a basic page (without forcing him to do
> > it)
> >
> > I think these are the key points collected from the previous discussion.
> >
> > BR,
> >
> > Alan
> >
> > 1 - https://lists.apache.org/thread/5dklb9r2k9vpl9jwpromdn0lcv3h0985
> >
>
>

Re: [VOTE] Features contributions should include Documentation

[Michal Lenc <mi...@seznam.cz>]

+1 for this, I think the wording of these points is a good compromise.

Btw, perhaps we could summarize what documentation pages we are missing. 
GitHub issue would be the best place for this?

Michal

On 11/6/25 20:58, Alan C. Assis wrote:
> As discussed in [1] we need to improve our Documentation and requesting
> Documentation from the author of the new added Features seems to be the
> best approach.
>
> So these are the proposals to be voted:
>
> - Anyone submitting a new features should write Documentation to it, which
> he/she is the author is knows more about that features than other people
> and could write better Documentation;
>
> - Anyone adding a new function (or a new resource such as ioctl, etc)
> should include it in the existing Documentation; If there is not
> Documentation for that Feature/Driver/whatever, then the Reviews should
> suggest the contributor to submit a basic page (without forcing him to do
> it)
>
> I think these are the key points collected from the previous discussion.
>
> BR,
>
> Alan
>
> 1 - https://lists.apache.org/thread/5dklb9r2k9vpl9jwpromdn0lcv3h0985
>

Re: [VOTE] Features contributions should include Documentation

[Nathan Hartman <ha...@gmail.com>]

+1 I think this is a sensible compromise.

On Thu, Nov 6, 2025 at 3:34 PM Alin Jerpelea <je...@gmail.com> wrote:

> +1
>
> On Thu, 6 Nov 2025, 21:08 Sebastien Lorquet, <se...@lorquet.fr> wrote:
>
> > +1
> >
> > I know I will hate the next time I submit something, but that is a good
> > thing.
> >
> > Sebastien
> >
> >
> > On 11/6/25 20:58, Alan C. Assis wrote:
> > > As discussed in [1] we need to improve our Documentation and requesting
> > > Documentation from the author of the new added Features seems to be the
> > > best approach.
> > >
> > > So these are the proposals to be voted:
> > >
> > > - Anyone submitting a new features should write Documentation to it,
> > which
> > > he/she is the author is knows more about that features than other
> people
> > > and could write better Documentation;
> > >
> > > - Anyone adding a new function (or a new resource such as ioctl, etc)
> > > should include it in the existing Documentation; If there is not
> > > Documentation for that Feature/Driver/whatever, then the Reviews should
> > > suggest the contributor to submit a basic page (without forcing him to
> do
> > > it)
> > >
> > > I think these are the key points collected from the previous
> discussion.
> > >
> > > BR,
> > >
> > > Alan
> > >
> > > 1 - https://lists.apache.org/thread/5dklb9r2k9vpl9jwpromdn0lcv3h0985
> > >
> >
>

Re: [VOTE] Features contributions should include Documentation

[Alin Jerpelea <je...@gmail.com>]

+1

On Thu, 6 Nov 2025, 21:08 Sebastien Lorquet, <se...@lorquet.fr> wrote:

> +1
>
> I know I will hate the next time I submit something, but that is a good
> thing.
>
> Sebastien
>
>
> On 11/6/25 20:58, Alan C. Assis wrote:
> > As discussed in [1] we need to improve our Documentation and requesting
> > Documentation from the author of the new added Features seems to be the
> > best approach.
> >
> > So these are the proposals to be voted:
> >
> > - Anyone submitting a new features should write Documentation to it,
> which
> > he/she is the author is knows more about that features than other people
> > and could write better Documentation;
> >
> > - Anyone adding a new function (or a new resource such as ioctl, etc)
> > should include it in the existing Documentation; If there is not
> > Documentation for that Feature/Driver/whatever, then the Reviews should
> > suggest the contributor to submit a basic page (without forcing him to do
> > it)
> >
> > I think these are the key points collected from the previous discussion.
> >
> > BR,
> >
> > Alan
> >
> > 1 - https://lists.apache.org/thread/5dklb9r2k9vpl9jwpromdn0lcv3h0985
> >
>

Re: [VOTE] Features contributions should include Documentation

[Sebastien Lorquet <se...@lorquet.fr>]

+1

I know I will hate the next time I submit something, but that is a good 
thing.

Sebastien


On 11/6/25 20:58, Alan C. Assis wrote:
> As discussed in [1] we need to improve our Documentation and requesting
> Documentation from the author of the new added Features seems to be the
> best approach.
>
> So these are the proposals to be voted:
>
> - Anyone submitting a new features should write Documentation to it, which
> he/she is the author is knows more about that features than other people
> and could write better Documentation;
>
> - Anyone adding a new function (or a new resource such as ioctl, etc)
> should include it in the existing Documentation; If there is not
> Documentation for that Feature/Driver/whatever, then the Reviews should
> suggest the contributor to submit a basic page (without forcing him to do
> it)
>
> I think these are the key points collected from the previous discussion.
>
> BR,
>
> Alan
>
> 1 - https://lists.apache.org/thread/5dklb9r2k9vpl9jwpromdn0lcv3h0985
>