What to do with READMEs that are already in the Documentation ?

[raiden00pl]

Same question as in apache/nuttx-apps#2156 but for nuttx repo

What to do with READMEs that are already migrated to Documentation ?

Should we remove them and only keep the entries in Documentation?

Maintaining two versions of the documentation will be a nightmare. Considering how poor we are at maintaining a single version of the doc, I think there is no point in keeping the READMEs in the code.

[acassis]

@raiden00pl maybe instead of only remove the files just put a comment inside it with link to the site documentation. So people will find the right direction

[raiden00pl]

In that case in which folders should we leave such READMEs? In all directories ? Currently there is no consistency as to where READMEs are and where they are not.

Putting a README in every directory makes no sense.

Putting the README in the top dirs (arch, audio, crypto, etc) seems more reasonable but after #10980 we'll have a link to the documentation in the main README.md so I don't know if it makes sense to duplicate this information.

I think more important is that the structure in Documentation reflects the structure of the repo, then navigation is much more natural and easy (at least from my perspective, i.e. working from terminal)

[acassis]

@raiden00pl I agree to make the structure in Documentation to reflect the structure. I was suggesting keeping the README inside the boards because I thought you didn't want to remove it. Also having the README inside each board with the link to the right documentation could be useful for someone new to NuttX.

Maybe instead the website link, it could be just a comment saying the board documentation is inside Documentation/platforms/arm/stm32f4/boards/stm32f4discovery/

This way we don't need to strictly force the boards/ structure for the Documentation/

[raiden00pl]

Maybe instead the website link, it could be just a comment saying the board documentation is inside Documentation/platforms/arm/stm32f4/boards/stm32f4discovery/
This way we don't need to strictly force the boards/ structure for the Documentation/

At the moment we have boards under Documentation/platforms/<arch>/<chip_family>/boards/<board_name> and it looks quite clear and logical for me.
Combining <arch> and <boards> doc in Documentation/platforms, even though it doesn't strictly reflect the repo structure seems OK.
Considering that for some chips we have different chip families in one directory (e.g. f1,f2,f3 in stm32), this solution is the only one that makes sense.

[btashton]

This sounds good to me.