You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by "raiden00pl (via GitHub)" <gi...@apache.org> on 2023/10/26 09:46:21 UTC
[I] What to do with READMEs that are already in the Documentation ? [nuttx]
raiden00pl opened a new issue, #11058:
URL: https://github.com/apache/nuttx/issues/11058
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.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] What to do with READMEs that are already in the Documentation ? [nuttx]
Posted by "btashton (via GitHub)" <gi...@apache.org>.
btashton commented on issue #11058:
URL: https://github.com/apache/nuttx/issues/11058#issuecomment-1783908702
This sounds good to me.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] What to do with READMEs that are already in the Documentation ? [nuttx]
Posted by "acassis (via GitHub)" <gi...@apache.org>.
acassis commented on issue #11058:
URL: https://github.com/apache/nuttx/issues/11058#issuecomment-1781408122
@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/
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] What to do with READMEs that are already in the Documentation ? [nuttx]
Posted by "acassis (via GitHub)" <gi...@apache.org>.
acassis commented on issue #11058:
URL: https://github.com/apache/nuttx/issues/11058#issuecomment-1780928064
@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
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] What to do with READMEs that are already in the Documentation ? [nuttx]
Posted by "raiden00pl (via GitHub)" <gi...@apache.org>.
raiden00pl commented on issue #11058:
URL: https://github.com/apache/nuttx/issues/11058#issuecomment-1783740378
> 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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] What to do with READMEs that are already in the Documentation ? [nuttx]
Posted by "acassis (via GitHub)" <gi...@apache.org>.
acassis closed issue #11058: What to do with READMEs that are already in the Documentation ?
URL: https://github.com/apache/nuttx/issues/11058
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] What to do with READMEs that are already in the Documentation ? [nuttx]
Posted by "raiden00pl (via GitHub)" <gi...@apache.org>.
raiden00pl commented on issue #11058:
URL: https://github.com/apache/nuttx/issues/11058#issuecomment-1780947578
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)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org