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 <[email protected]>
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
