search

apache / nuttx

Apache NuttX is a mature, real-time embedded operating system (RTOS)
https://nuttx.apache.org/
Apache License 2.0
2.62k stars 1.11k forks source link

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

Closed raiden00pl closed 10 months ago

raiden00pl commented 10 months ago

Same question as in https://github.com/apache/nuttx-apps/issues/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 commented 10 months ago

@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 commented 10 months ago

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 https://github.com/apache/nuttx/pull/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 commented 10 months ago

@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 commented 10 months ago

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 commented 10 months ago

This sounds good to me.