Add a "quick start guide" episode

[ehogan]

Short description of the material

Hi @ESMValGroup/userengagementteam,

I would like to propose adding a "quick start guide" episode.

The structure of this episode would be:

• Activate environment
• Configure ESMValTool
• Run example recipe

Having a "quick start guide" like this would lower the entry barrier for new users and would enable a user to quickly get started using ESMValTool, especially in those cases where they are working somewhere that already has ESMValTool installed and has data available (e.g. JASMIN, DKRZ, Met Office). The above sections would refer to the ESMValTool documentation for further information / incase the user is working in a different location.

We already have a draft "quick start guide" (developed by @mo-gregmunday) that we have been using at the Met Office, and @mo-tgeddes would create the PR, provided there are no objections :)

Branch and pull request Once you've started working, add the branch (and pull request) link.

[ehogan]

I did spot #52, which is a more in-depth version of what I am suggesting here.

[SarahAlidoost]

@ehogan good idea, I think the lesson "quick start guide" can come after episode 5. Please go ahead with submitting the pull request.

[remi-kazeroni]

Thanks for the suggestion @ehogan! That can be useful to have a quick start guide for users of machines with a central installation of ESMValTool (CEDA, DKRZ, ...) and access to data. Not sure if that is relevant to mention here but we already have some instructions here on how get access to these machines or the data pools here but that may not be very visible though.

[ehogan]

Thanks both! :)

@SarahAlidoost, since the purpose of the quick start guide is to lower the entry barrier for new users, I would argue that it should be episode 0. The quick start guide would reference the next few episodes, should more information be needed. Would that be ok? What do you think?

@remi-kazeroni, yes, my intention was for the quick start guide to link to other lessons / sections, as appropriate, and we can certainly add a link to the intructions you provide above :)

Thinking out loud, I wonder whether it would be worth creating an episode for "data managers" at the various sites? :)

[SarahAlidoost]

Thanks both! :)

@SarahAlidoost, since the purpose of the quick start guide is to lower the entry barrier for new users, I would argue that it should be episode 0. The quick start guide would reference the next few episodes, should more information be needed. Would that be ok? What do you think?

I thought the episode is for an advanced user. it should be OK. Looking at episodes 1 to 5, I think the episode 1-introduction is still useful for all users. So, perhaps "episode 2- quick start guide" ? Let's first have a look at the content of the quick start guide in a pull request, then we decide on the order of episodes. :)

[ehogan]

Sounds good @SarahAlidoost; we'll get the PR up first, then decide :) Thanks!

[remi-kazeroni]

@SarahAlidoost, since the purpose of the quick start guide is to lower the entry barrier for new users, I would argue that it should be episode 0. The quick start guide would reference the next few episodes, should more information be needed. Would that be ok? What do you think?

That might be misleading because some starting the tutorial might think that they can't use ESMValTool if they don't have access to DKRZ/Jasmin, ... which is not true. But let's see in the PR how to order the episodes 👍

Thinking out loud, I wonder whether it would be worth creating an episode for "data managers" at the various sites? :)

How would you define these "data managers"? Do you mean maintainers of the local ESGF data pools? Or obs pools?

[ehogan]

@SarahAlidoost, since the purpose of the quick start guide is to lower the entry barrier for new users, I would argue that it should be episode 0. The quick start guide would reference the next few episodes, should more information be needed. Would that be ok? What do you think?

That might be misleading because some starting the tutorial might think that they can't use ESMValTool if they don't have access to DKRZ/Jasmin, ... which is not true. But let's see in the PR how to order the episodes 👍

Great point @remi-kazeroni; we'll keep this in mind when writing up the episode :)

Thinking out loud, I wonder whether it would be worth creating an episode for "data managers" at the various sites? :)

How would you define these "data managers"? Do you mean maintainers of the local ESGF data pools? Or obs pools?

Good question; I was initially thinking the observational data pool because we're trying to get those data at the Met Office right now (we already have a method of obtaining model data via ESGF), but thinking about it it should be any data! :)

[rswamina]

@ehogan @SarahAlidoost @remi-kazeroni , I have a few questions/thoughts:

1. How much quicker can a quick start be without a pre-installed module? In my experience people rarely go beyond a Quick start unless they have to (which is a reason to have one, sure) but it will be good to identify who this is targeted at and any limitations.
2. Will this lesson be Bullet point 1 from Installation followed by the Configuration and Running your first recipe lessons or some condensed version of the latter two lessons?

I am not against the idea of a Quick start lesson but wondering how best it will stand on its own. As it is, with big improvements in documentation for installation, we should be aware of how best the tutorial complements the readthedocs page and serves a unique role. Happy to wait for the PR to see what it will entail.

[remi-kazeroni]

How would you define these "data managers"? Do you mean maintainers of the local ESGF data pools? Or obs pools?

Good question; I was initially thinking the observational data pool because we're trying to get those data at the Met Office right now (we already have a method of obtaining model data via ESGF), but thinking about it it should be any data! :)

Thanks for clarifying. Then, I would tend to say that an extra episode for this topic is rather not needed. It would only be relevant for a handful of developers and the instructions are likely to be very much system-dependant. Feel free to contact me and/or the Tech Lead Team if you wish to discuss the creation of an obs data pool. I also started a discussion on this topic in https://github.com/ESMValGroup/ESMValTool/issues/2630