suggestions for improvements of the installation documentation and quickstart guide

[remi-kazeroni]

Is your feature request related to a problem? Please describe. The reviewers of our IS-ENES3 deliverable D9.5 (Final ESMValTool version for IS-ENES3 (aka v2.8.0)) made very interesting suggestions for improvements after reviewing our report and trying to install and use ESMValTool. Most of them are related to our installation documentation which could be further simplified and shortened, especially for a "quickstart" guide. I reproduce the comments here to keep track of the suggestions:

We have some comments on the docs and installation:

• The Readme could mention the word “Installation”.
• Maybe add a simple section to the Readme for a quick Conda installation on Linux. To install EMSValTool on Linux in a new conda environment, you can use mamba create --name esmvaltool esmvaltool.

For more information on the installation, please see XXXX (links to the documentation).

-> Those who do not face problems with this quick (and most likely most common) guide do not have to go through the lengthy installation instruction.

• The “Getting Started” section describes the complete installation and configuration. But we would have expected a “Quick Start” to setup ESMValTool just for local testing.

A list of possible action items I see from these suggestions:

• [ ] Adding an installation section to our Readme and link to the 1-2 most used installation method(s).
• [ ] Splitting the installation documentation into sub-pages with one page per topic: conda package, source installation, docker, module load, ... In the quickstart guide we could only keep the "front page" that briefly describes all methods with links to all subpages.
• [ ] For a "quicker" quickstart guide, maybe explicitly recommend a quick installation method. We could also simply link to our quickstart guide episode of the Tutorial.

Would you be able to help out? Would you have the time and skills to implement the solution yourself? I'd be happy to take care of some of these items for the next release (even though the readme and tutorial are not in releases). But I would first like to hear opinions from @ESMValGroup/technical-lead-development-team and @ESMValGroup/userengagementteam 👍

[bouweandela]

Maybe we could move the installation and configuration pages one level up and add the simple mamba install -n esmvaltool esmvaltool, conda activate esmvaltool, esmvaltool config get_config_user, make some minimal edits to ~/.esmvaltool/config-user.yml, esmvaltool run examples/recipe_python.yml in the getting started guide as a replacement, with links to the full chapters?

[remi-kazeroni]

I'd suggest to discuss that in person at the upcoming workshop. That's certainly something we could discuss and start implementing during one of the coding sessions. Since the workshop starts right after the planned release date, better bump this to the next milestone

[zklaus]

It seems this has fallen through the cracks. It would be good to take it up soon.

[mo-gill]

Hi, we are currently working on the ESMValTool release for v2.11.0. We're wondering if you'd be able to finalise this issue by the end of next week (Friday 10th May).

If we don't hear anything from you by then we'll move this into the next milestone.

Edit: Otherwise, please let us know, and we'll move it into the next milestone for you :slightly_smiling_face:

[valeriupredoi]

@mo-gill be more gentle please: a message a la "it'd be great if you could finalize this issue etc, otherwise please let us know, and we will move it for M2.12" :grin:

[mo-gill]

@mo-gill be more gentle please: a message a la "it'd be great if you could finalize this issue etc, otherwise please let us know, and we will move it for M2.12" 😁

Apologies if it came across a bit harsh @valeriupredoi, this is my first time doing this :cry:, i'll edit the messages to something a bit more gentle!

[valeriupredoi]

@mo-gill absolutely no probs, mate! It's always nicer to be softer with users/devs - more likely they'll do the work if you are nicer to them :grin: (the message was fine, it's just the "If we don't hear anything from you..." that's a bit ultimatum-y)

[mo-gill]

@mo-gill absolutely no probs, mate! It's always nicer to be softer with users/devs - more likely they'll do the work if you are nicer to them 😁 (the message was fine, it's just the "If we don't hear anything from you..." that's a bit ultimatum-y)

That's a fair point, cheers @valeriupredoi !