Hello Vinícius, Thank you for taking the time and effort to make this reorganization. Like others who have given you feedback, I also have had frustration at times when trying to find things in the docs, so I think a good "top-down" design of the docs is a welcome change.
Thanks also for explaining why the PR looks big. It makes a lot more sense now. Thanks, Nathan On Wed, Sep 30, 2026 at 1:11 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 >
