Need documentation about CAM-SIMA directory structure

[nusbaume]

Issue Type

Documentation Update

Issue Description

As suggested by @gdicker1, it would be great to have documentation that described the directory structure of CAM-SIMA, and what the purpose of each subdirectory is, as that way any new developer or code contributor will know where they should look to find certain files or to add files of their own.

Will this change answers?

No

Will you be implementing this yourself?

Yes

[nusbaume]

Hi @gdicker1, it took us almost a year, but we finally have documentation on the directory structure in CAM-SIMA. Given that you were the one who came up with the original idea, it would be great to get your thoughts on the documentation before I close this issue. You can find the documentation online here:

https://escomp.github.io/CAM-SIMA-docs/design/directory-structure/

Please let me know if you think there should be any changes, or if anything is missing. I should note that one listed MPAS sub-directory (assets) doesn't actually exist yet, but will come in once PR #327 is merged. Thanks!

[gdicker1]

Thanks for remembering this @nusbaume!

I think this all looks good and will really help new users. I have feedback which are all just "nice to haves," this is a really strong basis.

1. A picture could really help this specific page. Especially with colors or ways to highlight the "external directories" to reinforce that nuance.
2. For the documentation in general, it can be really good to know when a page was last updated. Even the most helpful documentation becomes slightly out of date as development continues.
3. For the documentation in general, a link to the source code (for the docs) is really nice for open development. It would enable users like me to easily contribute when docs start diverging.

Nothing is missing, and nothing that needs changed. I may follow up on my feedback and ideas with my own PR to CAM-SIMA-docs.

[nusbaume]

Thanks @gdicker1! Those would all be great additions. I should note that there is currently a PR open to add the date created and date modified for each page, which you can find here:

ESCOMP/CAM-SIMA-docs#4

However all of your other suggestions I think are fair game, and I opened an issue on the CAM-SIMA-docs repo to add the picture you mentioned (as that might take a little work).

Anyways, I'll go ahead and close this issue, but certainly feel free to open a PR to any part of the docs if you find the time, and thanks again for the feedback!