Bug #20684: crunchstat-summary doc page should mention need to set up arvados repositories - Arvados

This turned into a bigger branch than it should've. While I was going over the documentation just to make sure I understood the ticket, I noticed that none of the pages for crunchstat-summary, arvados-client costanalyzer, or arvados-client shell mention the need to set up a package repository.

On the one hand, obviously they all need to. On the other hand, obviously this doesn't scale. We have a whole bunch of client tools that can, in principle, be installed independently of each other. But it just doesn't work for the documentation for every tool to include complete instructions for how to configure a package repository for five different distros, or else create and install into a virtualenv, and then configure your shell to use it. Readers don't want to read that, and we clearly don't want to write it.

So while I was looking at what our other client documentation says to get the lay of the land and find the most reasonable middle ground I could, I noticed our CWL Runner documentation includes half a dozen references to FUSE. Because we started that documentation by copying the FUSE documentation. Because our documentation includes too much boilerplate, so that's the only reasonable option. I fixed that.

Then to solve the real problem, what I ended up doing is expanding the setup-cli page a bunch, with a general recommendation to use a VM, strong advice to set up a package repository otherwise, and a more detailed list of all the client tools you can install. Not too detailed, just some explanation of what's what beyond just "Python SDK" and "CLI SDK." And now all the client tool pages include that notebox right at the top.

This still isn't great. I'm guessing a lot of people will just skip over that box. But it's the best I think I can do within the current structure of our documentation and half a story point. I think we need a larger ticket to have a group conversation to go over what we want all of our client tool documentation to look like—what pages provide common resources across tools, what structure is common across tool pages, what includes they use—and then implement that. But this ticket is clearly not that.

Actions

Copy link

Updated by Tom Clegg 10 months ago

LGTM.

Only one minor suggestion, and only related to a change that's already tangential.

While we're updating the cwl-runner page, "The Python SDK uses pycurl which depends on the libcurl C library" is better than just "the SDK ..." but in this context would it be easier to follow to say "The CWL runner uses pycurl ..."? (It's a second-order dependency, but is it really helpful to surface that here?)

The references to Debian 10 and Docker built in 2015 hint at a story to just bring all of those sorts of things up to date.

Actions

Copy link

Updated by Brett Smith 10 months ago

Tom Clegg wrote in #note-4:

While we're updating the cwl-runner page, "The Python SDK uses pycurl which depends on the libcurl C library" is better than just "the SDK ..." but in this context would it be easier to follow to say "The CWL runner uses pycurl ..."? (It's a second-order dependency, but is it really helpful to surface that here?)

Agreed, changed in 08070181e.

The references to Debian 10 and Docker built in 2015 hint at a story to just bring all of those sorts of things up to date.

Modernized the Debian instructions in 7da1ea409 (on all pages where it appears). Thankfully this list has gotten more stable over time so we don't need to be quite so specific about the version right now.

Actions

Copy link