Add explanatory info to intervention examples

[hjoliver]

The new interventions section is great, but the examples need explaining a bit so that users can understand how they work sufficiently well to extrapolate to similar-but-different use cases.

[This PR was motivated by a user at NIWA who tried to apply the first example (Re-run a Task) to re-run a succeeded task, and wondered why nothing happended downstream of it in that case.]

I've gone for adding a new tab (GUI, Tui, CLI, Explanation) so that the "advanced" explanation doesn't distract from the basic example unless the user wants to see it. Alternatively, it could go in a text box below the example.

If approved in principle I'll add cross-references and add minimal explanations to the other examples as well.

Requirements check-list

• I have read CONTRIBUTING.md and added my name as a Code Contributor.

[wxtim]

If we can get rid of "do things like" and make the list happily comprehensive I'd be happier.

Suggested change

	So Cylc allows you to take manual control of your workflow whilst it's running,
	to do things like edit a task's configuration, re-run a section
	Cylc allows you to take manual control of your workflow whilst it's running,
	to do things like edit a task's configuration or re-run a section

[hjoliver]

I was trying to keep this PR strictly to "explanatory info for the examples", rather than a more general revision (note there's a "whilst" in there too 😁 ) ... but I tend to agree with you on that point.

[wxtim]

I really like it as a concept, although I'm not completely convinced users will actually read it. I think that you will want @oliver-sanders approval for the idea.

[oliver-sanders]

IMO this is too technical, developers will understand it, but users probably won't (flows are an advanced concept). We should be able to explain this more simply without having to mention flows.

E.G:

Suggested change

	In this example, a failed task blocked the flow because downstream
	tasks depended on its success. Triggering the failed task to run again
	(if it succeeds this time) allows the original flow to continue.
	The flow will only continue downstream of a triggered task if it has not
	already traversed that part of the graph.
	So if you trigger a past task that did not block the flow, only the triggered
	task itself will run - unless you tell Cylc to start a new flow.
	In this example, a task has failed, as a result, some downstream tasks are not running.
	Triggering the failed task causes it to run again.
	If it succeeds, the downstream tasks will run and the workflow will continue.
	Note, any downstream tasks which have already run will not be re-run as a result.

[hjoliver]

I thought you might say that :-)

I don't think a "flow" is very technical. It's an intuitive concept with a very intuitive name. A single logical run of the workflow "flows" through the graph.

Your edit does get pretty close to describing what's going on without using the word "flow" but it stops short of saying how you can rerun "tasks which have already run" if you actually need to do that - which sometimes you might need to do.

[hjoliver]

The aforementioned NIWA user did need to - she was surprised that the flow did not continue after retriggering a succeeded task like it did on retriggering the failed one in the example.

[hjoliver]

Also, it's fine (and good!) to have more detailed "advanced" info available where appropriate so long as it doesn't distract from the core basic info. That's why I tried to hide it in a new tab.

What if we called it "advanced" rather than "explanation"?

[oliver-sanders]

I don't think a "flow" is very technical. It's an intuitive concept with a very intuitive name. A single logical run of the workflow "flows" through the graph.

"Flows" are not part of the minimal terminology / concepts required to use Cylc and are not covered in the tutorial. You only learn about flows when trying to do --flow=new which is a niche requirement, most of our users do not know what "flow" means and there is great confusion amongst those who have tried to use use them (as previously discussed).

But we don't need to talk about flows here, so lets avoid it.

[oliver-sanders]

Suggested change

	In this example, a failed task blocked the flow because downstream
	tasks depended on its success. Triggering the failed task to run again
	(if it succeeds this time) allows the original flow to continue.
	The flow will only continue downstream of a triggered task if it has not
	already traversed that part of the graph.
	So if you trigger a past task that did not block the flow, only the triggered
	task itself will run - unless you tell Cylc to start a new flow.
	In this example, a task has failed, as a result, some downstream tasks are not running.
	Triggering the failed task causes it to run again.
	If it succeeds, the downstream tasks will run and the workflow will continue.
	Note, any downstream tasks which have already run will not be re-run as a result.
	If you want to re-run downstream tasks, see :ref:`interventions.re-run-multiple-tasks`.

You'll need to add a interventions.re-run-multiple-tasks anchor in the next section to use this suggestion.

[hjoliver]

But you haven't addressed the core point that motivated this PR. I'll repeat it:

If we don't explain why the example works the way it does, users won't be able to apply their knowledge to slightly different use cases. In particular (and as motivated by an actual USER) they need to know (a) why rerunning a failed task typically has different "flow-on" effects than rerunning a succeeded task; and (b) how to make the succeed case flow on if they actually need that.

I don't think intervention documentation is the right place to stick to absolute basics. That's what the tutorial is for.

[oliver-sanders]

I think my suggestion explains this more clearly right?

As there is only one flow in this example, we can explain this in the same way we would have at Cylc 7.

[hjoliver]

(Our last two comments passed in the ether - I think you have mostly addressed my concerns now).

[hjoliver]

As there is only one flow in this example, we can explain this in the same way we would have at Cylc 7.

Yes and no - users also need to know why the workflow won't "flow on" after triggering a past task that did not block the flow.

You have sort-of addressed this by referring forward to "re-run multiple tasks", but IMO it would help to have a brief explanation of the sort I suggested in this example too, because it helps put the specific example in a wider context. (After all the section is called "Re-run a Task" (any task!) not just "Re-run a Failed Task).

[oliver-sanders]

Also, would it not make more sense to include this information in the body text (where it is always visible), rather than putting it into one of the tab groups? We want people to read this!

[MetRonnie]

IMO this should not be a tab, which is meant to be for your preferred choice of interacting with Cylc. Instead it should be a "spoiler" admonition or ordinary admonition

[hjoliver]

(Yes, see my comment just below!)

[hjoliver]

(It depends on whether we are trying to keep the "advanced" info somewhat hidden, to avoid scaring users with the most basic needs)

[oliver-sanders]

Ronnie suggested a "spolier" which hides the content.

[hjoliver]

Yep I like that.

[hjoliver]

Also, would it not make more sense to include this information in the body text (where it is always visible), rather than putting it into one of the tab groups? We want people to read this!

Haha, I agree, but I was trying to head off your expected response on "advanced" information as we've just been discussing 😁 but putting it in a place that required some opt-in by users.

[hjoliver]

BTW, "the flow" is a nice intuitive way to describe how a single self-consistent workflow run propagates through the graph.

So e.g., a failed task (when failure is not optional) will typically "block the flow". To my mind that's really not technical and is the clearest way to describe how the system actually works - even if we're not talking about starting new flows in the Cylc 8 sense (although, thankfully, new flows are a perfect fit for the same concept).