High level of complexity - we need a first pass quick user guide

[valeriupredoi]

I want to bring this forward and have a bit of discussion around it today when we'll all be in at the sprint (at 1pm CET). A few points I'd like to raise:

• whereas I really like the structure and content of this tutorial, I am starting to see it as code documentation in a slightly different incarnation - which it's starting to bring back the high complexity of the documentation, which is not good;
• a first-time unassisted user will most probably get lost from the get going in this tutorial unless assisted by one of us;
• more graphical media needs to be included, rather than terminal commands and text; arrows and colour blobs are always nicer than text;

Having said that, I believe we need to dedicate a lot of effort to finding out what's the best way to construct a first-pass, quick user guide that has a few key attributes:

• it's simple enough for the unassisted user to easily follow the steps alone;
• it's detailed just enough but not too detailed so the user can, at the end of their pass through, to get a small diagnostic run and get one plot;
• it comes pre-packaged with CMIP+OBS data and all the needed runtime files that will need only minor alterations;
• it's attractive! very important to have something that looks good from a graphical perspective (eg replace terminal commands written in .md with actual terminal snapshots that the user can copy&paste text from, have the workflow presented in flow charts, add plots, add videos or gifs too);
• it doesn't require gitHub membership, it doesn't care for continuous integration tests, but it allows the user to run a small number of integration tests on their work (and explains the basics of automated testing);
• it's portable ie one can download the quick user guide package and send it to a friend;
• it contains expandable sections with more detail and links to code documentation, but very importantly, these sections will expand only if prompted by the user

I am fairly sure if we don't get this sort of thing done first, then point the users to this tutorial and the documentation, they will not even bother looking at the tutorial, skim the documentation and next thing we know we get a dozen or so gitHub issues with questions like 'where do I get data from'. Anyways, up for discussiong this more later on :beer:

[BenMGeo]

So what do you think about the esmvaltool --demo idea. Where maybe even files/codes pop up, you are requested to hit y to go on, etc?

Not sure if this is done "easily", but I can imagine that it can be done.

[Peter9192]

@BenMGeo can we make this idea a bit more specific? What should it do. I suppose something like:

• Some small example data should be shipped with ESMValTool for a test/demo application
• You type esmvaltool run demo (new CLI) and then:
• The command line asks permission to make a new data directory in your CWD and copy the toy data there; you have to confirm with y
• The command line prints something like: "All set-up for a demo. To run your first recipe, type: esmvaltool run examples/recipe_demo.yml" and exits.
• You then copy the command and the demo runs.

Is that what you have in mind?

[BenMGeo]

Is that what you have in mind?

Pretty much, yes.

• Some small example data should be shipped with ESMValTool for a test/demo application
• You type esmvaltool run demo (new CLI) and then:

(Maybe to make sure it is not confused with finding a file called demo, make it esmvaltool demo)

• The command line asks your definition of the working directory (declaring how much space it needs) and use the toy data directory as the data directory and setup the demo config accordingly; report all files that changed
• The command line prints something like: "All set-up for a demo, do you want to run?" and (confirmed with y) runs your first recipe esmvaltool run examples/recipe_demo.yml
• report all files that where set up and where to find the output
• report how to run your first recipe again by typing: esmvaltool run examples/recipe_demo.yml and exits.

slight changes, but even easier for a first time user.

Actually, I'd also suggest to have a seperate repository for demo data at some point, or maybe using iris demo data, if this is possible. So you can install some small data that can be used for examples.

[rswamina]

@ehogan , @SarahAlidoost - Does the quick start episode address the issues for a simple start to the tutorial? Ifso, we can close this issue.

[ehogan]

@rswamina the quick start guide addresses some of the items mentioned in this issue, but not everything (there are some nice suggestions here!) 😊 Would it be worth discussing and taking forward some of these suggestions?

[valeriupredoi]

@LisaBock has this been addressed or was it an accidental close? :beer:

[LisaBock]

@LisaBock has this been addressed or was it an accidental close? 🍺

@valeriupredoi I tried to close some outdated issues. I missed that parts of these discussions not yet implemented. Sorry! I reopened the issue.