Project

General

Profile

Actions

Bug #20684

closed

crunchstat-summary doc page should mention need to set up arvados repositories

Added by Peter Amstutz 12 months ago. Updated 10 months ago.

Status:
Resolved
Priority:
Normal
Assigned To:
Category:
Documentation
Story points:
-
Release relationship:
Auto

Subtasks 1 (0 open1 closed)

Task #20715: Review 20684-user-install-doc-fixesResolvedBrett Smith07/10/2023Actions
Actions #1

Updated by Peter Amstutz 12 months ago

  • Target version changed from Future to Development 2023-07-19 sprint
Actions #2

Updated by Peter Amstutz 12 months ago

  • Assigned To set to Brett Smith
Actions #3

Updated by Brett Smith 12 months ago

  • Status changed from New to In Progress

20684-user-install-doc-fixes @ 0e21f0f4f9a5f828a339894bc8eb1882a42946ab - developer-run-tests: #3735

Workbench 1 retry developer-run-tests-apps-workbench-integration: #4042

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 #4

Updated by Tom Clegg 12 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 #5

Updated by Brett Smith 12 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 #6

Updated by Brett Smith 12 months ago

  • Status changed from In Progress to Resolved
Actions #7

Updated by Peter Amstutz 10 months ago

  • Release set to 66
Actions

Also available in: Atom PDF