You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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
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. TheInputDataset
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:
@NoraLoose thoughts?
The text was updated successfully, but these errors were encountered: