Creating documentation for different versions of NorESM

[TomasTorsvik]

@adagj , @gold2718 , @mvertens
We are coming to a point where we need to document different versions of NorESM, in particular NorESM2.1 and new developments for NorESM3(?) or NorESM2.X(?) or NorESM-dev(?).

At the moment we have a main branch that is just listing the different versions, the old noresm1 that we don't update, noresm2 where everything new has gone into so far, and noresm2.2 that documents only the difference from noresm2.

noresm2.1 will also be based on noresm2, so one strategy for this branch would be to do the same as for noresm2.2 and only include the differences and new updates relative to noresm2. I think this is the preferable way, as noresm2 is the CMIP6 version, and there is a chance that we may update the documentation, e.g. if there are new questions coming in. I think this is less likely to happen for noresm2.1.

For NorESM3 we should probably have a complete documentation that does not reference noresm2. We have some changes already now that are relevant for the development, but not for noresm2 and noresm2.1. Should we go ahead with a new branch for this now? Is there a preference for what to call such a development branch? I'm not sure the next release will be NorESM3, so maybe just noresm-dev for now? Maybe a problem if we need more than one development branch.

[MichaelSchulzMETNO]

I believe for now the documentation of the new versions should only contain the changes and add-ons . I suggest thus that we have two more branches, noresm2.5 (being "CMIP6-pluss") and noresm-dev being the branch that leads to the future noresm3.

[adagj]

Hi,
glad you ask Tomas. I disagree slightly with Michael's suggestion.

Referring to the meeting 18th of September:

• NorESM2.1 is the CMIP6+ version, and release date is early next year. It will be based on the NorESM2 framework, so for this version I suggest add-ons to the NorESM2 documentation

• NorESM2.5 (planned release is end of 2024) is based on a new framework, so for this version I think we need to start a new documentation. The development will go in the noresm-dev branch

• NorESM3, which will be the CMIP7 version, will be based on NorESM2.5 but it is uncertain at the moment how much the two will differ, so I think we can postpone deciding if that will mostly be add-on documentation or a new one

Cheers,
Ada

[TomasTorsvik]

Hi,
I have the same understanding as Ada regarding the upcoming NorESM releases. At the moment we are working towards a NorESM2.1 release.

From a technical point of view, the question is if we should branch off noresm2.1from noresm2 or from main. Branching from main makes more sense if we just document code changes relative to noresm2, since then we don't duplicate files between the noresm2 and noresm2.1 branches. If noresm2.1 documentation should be self-contained, we should branch off noresm2.

The same question applies to a noresm-dev branch that should target the NorESM2.5 release at the end of 2024. To start from main and add inn parts from noresm2, or start from noresm2 and remove CMIP6-specific stuff? Option 1 may be more sensible if we have time to review the additions, option 2 is probably quicker but we may have some remnants of CMIP6-specific stuff hanging around for a while.

[gold2718]

One consequence I see of incremental documentation is that it is breaking a lot of links. In presentations and other documents, I see a lot of links of the form: https://noresm-docs.readthedocs.io/en/latest/configurations/platforms.html.
These are all broken by the decision to use incremental documentation. That means that older presentations and other documents are no longer useful or must be rewritten.
This is leading to a lot of extra work in, for example, the upcoming NorESM user workshop.

[TomasTorsvik]

Agree, that was an unintended side effect. Maybe avoid using latest?

[TomasTorsvik]

I would like to make a branch for the noresm2.1 version. From our last noresm-core meeting, it seemed there was a preference to have a complete documentation for noresm2.1, not just differences relative to noresm2. In that case it makes sense to branch off from noresm2 documentation. I can do this after PR #11 is resolved.