Migrating the Tutorial out of Software Carpentry and related issues

[rswamina]

A discussion item from the November 2025 workshop was whether we should move out of the current Software Carpentry setup for the ESMValTool Tutorial.

Please add links/references and your feedback to this thread.

Some of the questions surrounding this are :

1. Should we move from Software Carpentry? See @ehogan's presentation slides for the motivation.
2. Should the tutorial be part of the ESMValTool repository or separate?
3. Are there technical issues associated with keeping them together or separate?
4. How hard would it be to update the tutorial in coordination with ESMValTool releases?
5. How would the role of the User engagement and Technical teams change if the tutorial is in the ESMValTool repository?

[katjaweigel]

Maybe include the tutorial into the release: Release first the Core, then the Tool and last the Tutorial to make sure it is in line with the release?

[ehogan]

1. Should we move from Software Carpentry? See @ehogan's presentation slides for the motivation.

Yes 😊

2. Should the tutorial be part of the ESMValTool repository or separate?

The question here is about the ESMValTool repository rather than the ESMValTool documentation, correct?

I feel there was agreement during the presentation that the ESMValTool Tutorial should be part of the ESMValTool documentation (Evidence: One of the four corresponding forms of documentation within the Diátaxis approach is Tutorials. Including tutorials within the ESMValTool documentation fits within the Diátaxis approach. It is my understanding that the community have agreed to adopt the Diátaxis approach. All of this leads me to say that the ESMValTool Tutorial (and other new tutorials) should be part of the ESMValTool documentation.).

During the presentation, there were concerns raised around "providing a single link to the ESMValTool Tutorial" and "not seeing headers from other parts of the ESMValTool documentation in the navigation". I believe it should be possible to retain / enable these features even if the ESMValTool Tutorial is part of the ESMValTool documentation.

Including the ESMValTool Tutorial in the ESMValTool repository would ultimately reduce the workload of the UET, since they would benefit from the technical infrastructure the ESMValTool repository already provides (e.g. testing the builds of the documentation, deploying to RTD, checking the links (which is currently being implemented), etc.). Also, since the ESMValTool Tutorial would be in the same repository as the code, the content for the ESMValTool Tutorial could be updated at the same time as the code (more on this later).

3. Are there technical issues associated with keeping them together or separate?

I don't foresee issues, just advantages and disadvantages of the approaches (as details in the slides).

4. How hard would it be to update the tutorial in coordination with ESMValTool releases?

Ideally, the content for the ESMValTool Tutorial would be updated at the same time as the code. This means the content for the ESMValTool Tutorial will always be up-to-date with the code at release time. This will require members of the UET to perform reviews of PRs containing ESMValTool Tutorial content changes. I hope that, as the UET shares knowledge with the community via these reviews (specifically how to write for the needs of a user who wants a learning experience), the reviews will become less onerous for the UET.

5. How would the role of the User engagement and Technical teams change if the tutorial is in the ESMValTool repository?

In my opinion, regardless of where things are located, the roles of the UET and TLT should not change.