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
