Arvados

I agree this is a non sequitur in its current place, and it would make more sense at the end of git setup page, at the first point where it's expected to work and failure suggests "stay on this page and check your work", not "go back to the previous page and check your work."

• Mention that the job won't actually run yet
• Use an abbreviated commit hash, and check the API response to confirm it was resolved to the full hash. Might be a little more convincing than just "didn't get this error". ("master" will be resolved to a full hash too, but it might be less smooth to explain what you should see in the response. "You should see 522404b2066c8b635a240f79dd4bf652479afadb" vs. "You should see the same commit hash that you see at the top of https://github.com/curoverse/arvados/commits/master.")

Tom Clegg wrote:

I agree this is a non sequitur in its current place, and it would make more sense at the end of git setup page, at the first point where it's expected to work and failure suggests "stay on this page and check your work", not "go back to the previous page and check your work."

As the guide is currently written, it's not runnable there, because no repositories exist in the system. That doesn't happen until "Create standard objects," which is a little later, because you also need a shell node to create those objects.

Running it at the end of "Create standard objects" is the soonest we could do it. It feels a little out of place there, though.

We could move it to the top of the Crunch dispatch install guide, as a way to check that all the prerequisite components are set up correctly before proceeding.

I think it would be easy + helpful to make two more changes:

• Mention that the job won't actually run yet
• Use an abbreviated commit hash, and check the API response to confirm it was resolved to the full hash. Might be a little more convincing than just "didn't get this error". ("master" will be resolved to a full hash too, but it might be less smooth to explain what you should see in the response. "You should see 522404b2066c8b635a240f79dd4bf652479afadb" vs. "You should see the same commit hash that you see at the top of https://github.com/curoverse/arvados/commits/master.")

Both of these sound good to me.

Brett Smith wrote:

As the guide is currently written, it's not runnable there, because no repositories exist in the system. That doesn't happen until "Create standard objects," which is a little later, because you also need a shell node to create those objects.

Running it at the end of "Create standard objects" is the soonest we could do it. It feels a little out of place there, though.

Agree.

We could move it to the top of the Crunch dispatch install guide, as a way to check that all the prerequisite components are set up correctly before proceeding.

I like this idea: "If everything has gone well so far, we can create a job: [...] Now we can see it's queued, waiting for us to set up the infrastructure to run it... so let's do that."

LGTM -- just two nits:

"your collection's content address" seems a bit mysterious -- afaics we haven't created a collection in the install guide yet, and it might not be obvious enough that we use "portable data hash" and "content address" interchangeably. Is it worth putting "echo -n |arv-put --portable-data-hash -" in front of this, to make it concrete? The output of that command should always be 4c62f0a0d2344608e5f197894beb6fb5+47 so we wouldn't even need a "put yours here" part.

"either because it doesn't exist, or the user running the API server doesn't" - seems like it should be "because either A or B" or "either because A or because B" or even just "either A or B".