search

NorESMhub / NorESM-docs

Documentation of the NorESM model system and components
https://noresm-docs.readthedocs.io/en/latest/
GNU Lesser General Public License v3.0
4 stars 9 forks source link

Create NorESM2.5 documentation for developers #37

Open adagj opened 2 months ago

adagj commented 2 months ago

I believe it is time to start a new documentation for NorESM2.5. Initially, this should be targeted towards developers only. We can include information on how to use profiling and timing (Johannes has already started documenting this), where to find simulations and test cases, technical details on branches, where to find initial conditions and restart files. And xmlchange, git ++++. Do we start from scratch? I'm thinking that is a good plan, and then we can add useful parts from the noresm2 documentation at a later stage when we want to make it more user friendly. What are your thoughts?

MichaelSchulzMETNO commented 2 months ago

It would be also useful to keep one table ....google sheet, github documentation (?!?)...., where info on simulations is stored by any developer running important simulations. I believe the categories for such a table could be : Name of case, compset, components coupled, forcing, period of simulation, storage location, remarks on purpose and specifics of simulation, diagnostics available and location of these, comments on results, person doing the simulation.

mvertens commented 2 months ago

@gold2718 just pointed me to the following github approach that CESM is using - https://github.com/NCAR/amwg_dev. I think this is what we want to do for NorESM. I would propose in NorESMhub.

adagj commented 2 months ago

Agree! That was a useful page I think. Maybe we can discuss this on the core meeting on Thursday? @DirkOlivie In addition to simulation overview, I think it will be useful to also have a documentation page. For profiling, streams, diagnostics ++

adagj commented 2 months ago

Thay also have a spread sheet: https://github.com/NCAR/amwg_dev/discussions/549

oyvindseland commented 2 months ago

I agree that it is a good topic for discussion on Thursday

mvertens commented 2 months ago

I think there are two distinct topics here. Documentation of the model and its development (e.g. profiling, etc) and documentation of the experiments. These require very different solutions.

TomasTorsvik commented 2 months ago

For the documentation of the model, I think a major revision could be useful, but I'm not sure we need to start from scratch. Technically, writing the documentation as rst files and publishing on Read the Docs works well enough in my view, but I haven't looked at alternatives.

Structurally, we have a challenge that we want to maintain (or at least, keep alive) documentation for several versions of NorESM. This is why the latest version of the documentation is very sparse, and mostly provides links to the documented version of NorESM. We have a problem that pages may exist only for one version, so jumping between versions leads to an error. I tried to fix this earlier, but was not successful.

MichaelSchulzMETNO commented 2 months ago

Finally - if "a lot" changed, then I think there is no way around duplicating the-latest-version-documentation into a new-version-documentation and then maintaining it "separately", adding also a specific section "whats new in version x.x" .

adagj commented 2 months ago

For NorESM2.5, leading to NorESM3 documentation, I suggest we start from scratch and add what is needed for developers to find information (mainly pointing to already existing documentation like CESM, ADF, FATES ++), and some recommendations for model set up, xmlchange, where to create and store cases, how to do profiling, how to run BLOM with hybrid vs. isopycnic grid... Information which is needed for development, but not write a user guide at this point

mvertens commented 2 months ago

I think Ada's recommendation makes sense.