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 >
