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