Reduce complexity for new users: beginner mode

[aidanheerdegen]

During a discussion with @AndyHoggANU about learning and using the new payu branch features and autogenerated UUIDs he asked if there was a way to lower the barrier of entry for new users.

Could we have a "beginner mode", which helps users, with more verbose output, maybe asking questions to confirm actions?

It certainly technically possible. but would require some user feedback on what they find confusing, and hopefully what they would find helpful.

@AndyHoggANU and @aekiss could you comment with things you found confusing? And encourage any other users to do the same?

[chrisb13]

Thanks for suggesting this idea @aidanheerdegen, I think it's really interesting concept.

I wonder if beginner mode could be a means to triage the user into their relevant workflow, some key questions that might help the user into using payu setup in the relevant way are described below.

Examples could include, do you wish to....:

• "run an experiment from a config" (gives a link to access hive instructions on how to clone )
• "use an existing restart file" (links to the updated how to use payu doc and gives a link to experiments to use, e.g. https://access-om3-configs.access-hive.org.au/Experiments/);
• "share this experiment later" (gives a link to access hive instructions on how to attach a personal remote or access-community-Hub and does a ssh clone rather than a https one)
• "share your config developments" (gives a link to access hive instructions on how to push your config changes onto your own fork/access-community-Hub and then make a PR onto ACCESS-NRI);
  etc
  Note how they are ordered in order of "user experience level". It should also be possible to ask these questions later and the instructions allow people to change there "application" later.

There's some preceding discussion around related issues on this topic already. Whilst this suggestion could be a wonderful addition to helping new users, it would also need to be coordinated with some of the underway and discussed suggestions.

(Not exhaustive) examples include:

• Re: current update of payu docs led by @ccarouge. "General payu docs for Run a Model section" General payu docs for Run a Model section ACCESS-NRI/ACCESS-Hive-Docs#1107. See related issue and sub-issues: "General how to use Payu Docs" General how to use Payu Docs ACCESS-NRI/ACCESS-Hive-Docs#978
• Re: point of friction/confusion for users who want their remote branch name to match the name in metadata and archive path. Related: #ocean-seaice > OM3 25km IAF release and spinup run @ 💬
• Re: "Add visual cues to help user know the relevance of rose-cylc and payu documentation." Issue: Add visual cues to help user know the relevance of rose-cylc and payu documentation. ACCESS-NRI/ACCESS-Hive-Docs#1078
• Re: Hosting experiment repository on Github: a workflow for users for publications and Explainer: Workflows for users who wish to share or develop experiments and configurations. See PR and issue

ping'ing @ccarouge @atteggiani @paigem as I imagine they don't watch this repo.

[aekiss]

Beginners would be the best people to ask about barriers for beginners (e.g. post a link to this issue on the hive forum), but as an experienced user I found the auto-generation of branch names confusing and inflexible, and it imposes barriers to having a common repo for multiple experiments - see long discussion and suggested improvements starting here #ocean-seaice > OM3 25km IAF release and spinup run @ 💬

[aekiss]

Git provides helpful context-relevant suggestions on the command line - perhaps payu could do that?

[aidanheerdegen]

Beginners would be the best people to ask about barriers for beginners (e.g. post a link to this issue on the hive forum)

Thanks. Yes I was thinking to do so after getting some initial feedback, but please do feel free to let any beginner users you know that their feedback is welcome here, or pass on their feedback.

[ccarouge]

Considering I don't use payu very often, I consider myself a beginner each time I do. What I found confusing was the abundance of names to choose or use simply to do a "payu clone". I'm trying to get a generic payu page up on the ACCESS-Hive, so I tried to give purpose to all these names (https://docs.access-hive.org.au/pr-previews/1107/models/run_a_model/payu/#get-the-model-configuration). But a generic "payu clone" command would read something like:

cd <configurations-directory>
payu clone -b <experiment_name> -B <remote-branch-name> <remote-config-repository> <control-directory>

That's an intimidating command with a lot of pieces of information to put together before doing anything with payu. And one of the reasons I'm not giving the generic command on the payu page I'm writing and that I am using a specific example directly.

I haven't read the discussion on experiments in the same control dir. that @aekiss has linked, but the statement "payu uses branches to differentiate between different experiments in the same local git repository." on the payu page which I got from the Run ACCESS-OM2 page, I believe, doesn't make much sense for me. I would assume that people who want to run different experiments from a single configuration are likely to want to run these at the same time (sensitivity experiments type thing). So having them as branches in the same local repo isn't helpful. However, having them backed up in the same personal remote repository using different branches makes a lot of sense to me.

I'm not sure any of this helps design prompts and feedback from payu commands (although one could run payu clone without any command-line inputs and be prompted for all the names needed instead, with explanations, and payu builds the command internally from the user input).

[aidanheerdegen]

I found the auto-generation of branch names confusing and inflexible

I think this is a mistyping, payu doesn't auto generate branch names. The user chooses the branch name, payu generates an "experiment name", which is what it uses to name the work and archive directories, see the docs for more detail:

https://payu.readthedocs.io/en/stable/usage.html

[aidanheerdegen]

Considering I don't use payu very often, I consider myself a beginner each time I do. What I found confusing was the abundance of names to choose or use simply to do a "payu clone"

It's a good point. This syntax is really targeting automated use-cases, so we can generate a single command that will clone a specific branch from a specific repo at a specific commit and specifying the location of the files to restart the model.

It is also how we've generally told people to clone supported configurations because we had no other useful examples.

However, ultimately I would imagine the most common use-case, and the one we'd use in documentation, would be cloning a control experiment. In this case the common GitHub forking model would be preferred. In this way users would have a repo they could push their own experiments back to without any further configuration. And they would have a copy of the control experiment they are backing their own experiments on.

Up to this point however, we have no control experiments to use as an example.

[ccarouge]

@aidanheerdegen I was thinking about this. I was wondering how difficult it would be for payu clone to prompt the user for the info it needs instead (or in addition) to command-line arguments. So you could have:

payu clone
What repository do you want to clone from?
<user gives the path/URL>
What branch do you want to base your experiment on?
<user gives the branch name>
...

Same info to give but payu does the matches between the info and the command-line options (or whatever) behind the scene. A bit more human-friendly maybe? The prompts could refer to specific documentation pages etc.

[aidanheerdegen]

I was wondering how difficult it would be for payu clone to prompt the user for the info it needs instead (or in addition) to command-line arguments

It's a good idea. Thanks.

I think someone else suggested "like gh" when it prompts for info with gh auth.

[Qian-HuiChen]

The interactive prompt sounds like an excellent idea! I am happy to implement this