Create NorESM2.5 documentation for developers

[adagj]

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]

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]

@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]

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]

Thay also have a spread sheet: NCAR/amwg_dev#549

[oyvindseland]

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

[mvertens]

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]

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]

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]

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]

I think Ada's recommendation makes sense.

[adagj]

We'll try to use the noresm3_dev_simulations wiki to communicating noresm2.5 recipes

[adagj]

Instead of making a new online documentation for NorESM2.5, we have started a wiki: https://github.com/NorESMhub/noresm3_dev_simulations/wiki

However, the NorESM3 user guide will be in noresm_doc