Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

C-Star documentation restructure #224

Open
1 of 6 tasks
dafyddstephenson opened this issue Jan 24, 2025 · 1 comment
Open
1 of 6 tasks

C-Star documentation restructure #224

dafyddstephenson opened this issue Jan 24, 2025 · 1 comment
Assignees
Labels
documentation Improvements or additions to documentation jira-story Auto-create a corresponding story on JIRA

Comments

@dafyddstephenson
Copy link
Contributor

dafyddstephenson commented Jan 24, 2025

Related: #93

Right now, most doc pages are tutorials (labelled examples) that go into more detail than necessary to the tutorial in order to make sure C-Star functionality relevant to the previous tester protocol is covered, while still missing coverage of other functionality. All of these non-tutorial-specific details should be covered in separate guide pages that go deeper into a specific area.

Meanwhile, the existing tutorials should really be effectively one long tutorial split over several pages, but some potentially confusing inconsistencies were introduced to tick all the boxes of the testing protocol. For example, Examples 1 and 2 (building & exporting / importing & running) cover effectively the same Case, but with two different blueprints, in order to cover both netcdf and yaml InputDataset support. They should instead both relate to the same blueprint: the one that was built and exported should be the one that is imported and run. Meanwhile, descriptions of the different InputDataset possibilities described more thoroughly in a separate guide specific to the InputDataset class.

My thinking is to use netCDF input data for the "1. building and exporting...", "2. importing and running...", and "3. Restarting and running..." tutorials, with a note box in the former informing the user that they can build this input data using roms-tools by following the "4. Preparing...." tutorial. The InputDataset how-to guide would separately go through the nuances of yaml vs. netcdf source files.

I would also suggest that the notebooks cover running ROMS locally, but point to the how-to guide on running on a HPC (which following recent developments is basically the same anyway). This way, an interested/casual reader will have everything they need to follow along with most of the tutorials, even if we haven't made them a Perlmutter guest account.

I suggest:

  • Rename "Examples" -> "Tutorials"; add a "Guides" section
  • Add a guide page "Working with InputDatasets"
  • Add a guide page "Working with AdditionalCode"
  • Move both "Tracking runs..." pages to the "Guides" section as "Running on supported supercomputers" and "Running on other computers"
  • Make it so the "imported" case in (2) is the same as the "exported" case in (1) (netcdf, locally run)
  • Slim down the existing tutorials and refer to the guides for particulars that are not essential to the tutorial

@NoraLoose thoughts?

@dafyddstephenson dafyddstephenson added documentation Improvements or additions to documentation jira-story Auto-create a corresponding story on JIRA labels Jan 24, 2025
@dafyddstephenson dafyddstephenson self-assigned this Jan 24, 2025
Copy link

github-actions bot commented Jan 24, 2025

This issue has been linked to Jira story CW-647.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation jira-story Auto-create a corresponding story on JIRA
Projects
None yet
Development

No branches or pull requests

1 participant