Refactoring so separate general for feature specific documentation

[JanStreffing]

@christian-stepanek pointed out that

we have to somehow split our documentation efforts in two parts:

• Details on the overall modelling approach (e.g. standards to be followed - to be communicated to everyone that uses the model)
• Details on specific methodologies (e.g. how a specific modelling task, like hosing, can be tackled - information to be available to those interested when the need arises)

I agree that large features should live in their own section inside the documentation. Currently the structure is:

Before you start
    Licencing
    Repository registration
    Supported HPCs
Step by step
Releases
    AWI-CM3 v3.1
    AWI-CM3 v3.0
Contribute
    Personal model changes
    Permanent model features
    Improving the documentation
How to
    Cite this model
    Measure which component is limiting the throughput of the coupled model
    Generate OASIS3MCT remapping weights for large grids (offline and MPI+OMP parallel)
    Select an SSP or RCP scenario
    Change the number of vertical levels for pressure level output of OpenIFS
    Control orbital parameters
Workfolder contents
    Before the time integration of the model
    Additional files after the time integration of the model
    Detailed description of coupling files and which ones can be generated on the fly

I am fully open to refactor this structure, as this grew over time, without much planning. Let's discuss here what structure would be most suitable.

Adding @tsemmler05 @fernandadialzira @pgierz @a270067

[christian-stepanek]

Hello Christian,

I` agree. I would suggest to discuss at: #10

Do we have a real need for in internal documentation that is not visible to outsiders? If so, what would we document there that can not be documented publicly. Note that we already have an internal only support area where we can solve problems that we might not what to share with everyone.

Cheers, Jan

I think that we do not discuss state secrets here, but it may be awkward to read group internal strategies (preferred resolution, model version, etc.) at a location that is accessible to outsiders. I think points as in the document that I provided attached to the email are such kind of information.

Any kind of howtos should probably go on the publicly available space. Any strategy documents should be provided in a way that are accessible internally only, but it must be done in a way that new modellers will not overlook this kind of information. Maybe a AWI-ESM3 specific confluence page where both Climate Dynamics and Paleoclimate Dynamics outline their strategies? (I know, yet another confluence page :o/ - if you have a better idea, please put it here.)

[pgierz]

To keep it all in one place, a copy/paste of one of my emails.

---

Moin together,

I would second Jan’s question: what is required “only” internally? Note than Jan and I will at some point merge the AWIESM 2 and AWICM 3 documentation into one single place.

Best
PG

[fernandadialzira]

Hello Christian,

I` agree. I would suggest to discuss at: #10

Do we have a real need for in internal documentation that is not visible to outsiders? If so, what would we document there that can not be documented publicly. Note that we already have an internal only support area where we can solve problems that we might not what to share with everyone.

Cheers, Jan

I think that we do not discuss state secrets here, but it may be awkward to read group internal strategies (preferred resolution, model version, etc.) at a location that is accessible to outsiders. I think points as in the document that I provided attached to the email are such kind of information.

Any kind of howtos should probably go on the publicly available space. Any strategy documents should be provided in a way that are accessible internally only, but it must be done in a way that new modellers will not overlook this kind of information. Maybe a AWI-ESM3 specific confluence page where both Climate Dynamics and Paleoclimate Dynamics outline their strategies? (I know, yet another confluence page :o/ - if you have a better idea, please put it here.)

Shouldn't we keep these strategies mostly on the project management page on github? In this sense we separate what is intended to be available from what we are still discussed. I also suggest that the modellers sign up for e-mail updates of this section, so the information is not overlooked. The confluences page can be another step that makes things more complicated as to adding more channels. I intend to update the models part even more in October, and we can include the links to the documentation there, and the contact for those who intend to get access to more in depth discussions...

[christian-stepanek]

github is good. We just need to make sure that people are aware of it. The E-Mail updates may be a suitable option.

[JanStreffing]

We just need to make sure that people are aware of it.

We can link the documentation and support websites on the readthedocs. Ultimately new users have to be directed to the first resource (the public documentation?) by their supervisors. I can also setup up a "Welcome to AWI-CM/ESM3" email with the respective links. Then I would just need to be told who to send it to.