Clarify --include-retries docs and fixes

[plaindocs]

• switch options in examples to match usage
• clarify --include-retries and add example

CC: @jayco

[ticky]

Liking this change! Got a couple of little bits of feedback on the words (which are mostly my own from the other day 😇)

[ticky]

I wonder if this makes it clearer? “Retried” really feels like it does double duty here:

Suggested change

	By default, only artifacts from the most recent job in a chain of retried jobs are downloaded.
	To include artifacts from previous retried jobs, use the "--include-retried-jobs" flag:
	By default, only artifacts from the last job in a chain of retried jobs are downloaded.
	To include artifacts from superseded jobs, use the "--include-retried-jobs" flag:

[plaindocs]

I'm less keen on superseded, because if I read that I'd be wondering if it meant something specific in this context. We could just use "from previous jobs"

Huh, that was unintentional:

[ticky]

I’m just not sure “previous jobs” conveys “previous tries of this step” though, it seems ambiguous whether this means “prior jobs in the build” or something else

[plaindocs]

Yeah, I agree. How about

Suggested change

	To include artifacts from previous retried jobs, use the "--include-retried-jobs" flag:
	To include artifacts also from all retried jobs belonging to this step, use the "--include-retried-jobs" flag:

"Also", to make clear that it is as well as the last one. What do you reckon?

[plaindocs]

CC @ticky

[ticky]

I’m not sure this solves for the ambiguity in “retried,” and do we otherwise expose the step/job dichotomy to users?

[plaindocs]

Good point. I'll ponder and reword tomorrow.

[plaindocs]

We expose step just a couple of lines above, on line 35. But if we're not specifying a job ID, we're just using the artifact path, right, so this flag is just saying "get all the stuff, not just the most recent stuff", so mentioning the step isn't helpful. This might be better:

Suggested change

	To include artifacts from previous retried jobs, use the "--include-retried-jobs" flag:
	To include matching artifacts also from previous retried jobs as well as the most recent, use the "--include-retried-jobs" flag: