Hi Matteo, Thanks, and your nervousness is fair! Of course it is :)
>From my side, personally, I tend to scale things up. I can do small contributions when that is what is needed, and bigger ones when the change itself asks for it. For this PR it is hard for me to split it further, because I already know what I am changing and why. It does not invalidate your point, true. But also do not invalidates mine either: a big diff like this should make anyone nervous, and yet it is shallow, and the diff shows that. Most of it is pure renames, where not one byte of content changed, and board pages that gained a single '.. tags::' line. What is really left to read is a small set of pages with rewritten link targets, plus the ten pages with new text, and those ten are named one by one in the PR. On doing it one chapter at a time: I tried. What I noticed (and maybe I didn't do it well), is that the redirect table and the root toctree are global. So after each chapter, the sidebar is half old and half new, and every intermediate state is a site that is worse than both ends. I would rather hand you one state that builds clean than five states that do not. For "in case something gets missed": that is exactly what the script does. It takes every page outside the ten, erases what a move touches, and requires the old and new text to be byte for byte identical. If one word changes anywhere else, it exits non-zero and names the page. That is the check I could not do by eye either. And please, no rush. If this takes a week or two of review, that is fine by me. I would rather it go in slowly and correct, and then everyone finally gets this new documentation "outfit". One more thing, so you know where this goes. I have already revised 50 pages against the code, and they are not in this PR. I think NuttX grew up quite a lot faster than its documentation, and a good part of what is written is legacy. Those 50 will come one by one, page by page, and there I will really need the community's help to fix them. Vinicius On Wed, Sep 30, 2026 at 8:16 PM Matteo Golin <[email protected]> wrote: > > I like the proposed layout and changes a lot. I agree the documentation > could really use this much needed improvement. > > I am, however, not convinced that this is impossible to do in smaller > changes. I think you could re-organize one top-level chapter at a time and > that would still be better to review. How come it's not possible to > restructure individual sections? Even if you still need to touch links in > other pages, that's fine; still a smaller diff. I'm just a little nervous > merging this in case something gets missed. > > Best, > Matteo > > On Wed, Sep 30, 2026 at 1:10 PM Vinícius May <[email protected]> wrote: > > > Para: [email protected] > > Assunto: [DISCUSS] Documentation reorganisation (PR #20413) > > > > > > Hi all, > > > > I want to explain why I wrote PR #20413 before anyone looks at the diff, > > because the diff is big and the reason matters more than the size. > > > > The problem. > > Our documentation pushes people away. It is disorganised, > > it is outdated against the code in many parts. A newcomer who opens it > > does not > > find where things are. Whenever I shows NuttX to someone, I receive > > this feedback. > > > > By the way, NuttX itself is small and tidy. The docs are not, > > and that gap costs us contributors. > > > > Why it has to be one big change at this first commit? > > Like I explained there, I tried to do this in small steps and > > it does not work. Not at all. We are reorganizing around 1500 pages. > > Moving a page rewrites every link that points to it, > > so any small move still touches hundreds of files. Worse, if someone > > fixes the text of a page today and I move that page tomorrow, we > > conflict. The move has to happen once, in one go. > > > > What this PR does and does not do? > > It only changes where pages live. > > Of the 1577 .rst pages, 1567 keep the text that is already in master. > > > > Ten pages have indeed a new text, and nine of those are just the > > landing page of a new > > chapter. 520 redirects keep every old URL working. There is a script > > (need to push it to PR) > > so you can check that claim yourselves (what we really need to do, for > > sure). > > > > Why I think it is worth accepting? > > Well, this is the painful step that makes > > the next ones easy. Once every page sits under the subsystem it > > describes, fixing the content becomes page by page: one page, one > > commit, one small PR. Anyone in the community can take a page they know > > well, check it against the code, and fix it, without stepping on anyone > > else. That is the part I cannot do alone, and everyone will have the > > opportunity to help to fix. > > And everyone will no longer feel a lack of motivation because now > > things will be right organized. > > Mainly because that is the part that actually fixes the outdated text. > > > > So: this PR is the container. The content review is the next phase, and > > it belongs to all of us. > > > > The structure, as requested: > > > > CURRENT (19 top-level) PROPOSED (9 top-level) > > Introduction Introduction > > Getting Started Getting Started > > Contributing Supported Platforms > > Inviolables Guides > > Supported Platforms OS Design > > OS Components API Reference > > Applications Applications > > Implementation Details Developing NuttX > > API Reference About > > FAQ, Debugging, Testing, Guides, > > Standards, Security, Glossary, > > Logos, Tags Index > > > > Nothing was deleted. Every old chapter is still there, one level down. > > Feedback welcome, especially on the nine chapter names. > > > > Thanks, everyone! > > Let's stay together! > > > > BR, > > Vinicius > >
