+1 On Wed, Sep 30, 2026 at 3:15 PM Nathan Hartman <[email protected]> wrote:
> 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 > > >
