Support #17165

Work on user guide & training

Added by Peter Amstutz about 1 year ago. Updated 8 months ago.

Status:
Resolved
Priority:
Normal
Assigned To:
Category:
CWL
Target version:
Start date:
02/03/2021
Due date:
% Done:

100%

Estimated time:
(Total: 0.00 h)
Story points:
-
Release relationship:
Auto

2021-02-04_12-48.png (53.3 KB) 2021-02-04_12-48.png Nico César, 02/04/2021 05:48 PM
2021-02-09_17-29.png (42.1 KB) 2021-02-09_17-29.png Nico César, 02/09/2021 10:30 PM
2021-02-09_17-28.png (210 KB) 2021-02-09_17-28.png Nico César, 02/09/2021 10:30 PM
2021-02-09_17-29_1.png (200 KB) 2021-02-09_17-29_1.png Nico César, 02/09/2021 10:30 PM

Subtasks

Task #17329: practice runResolvedNico César

Task #17334: Review 17165-vscode-training-docResolvedNico César

Associated revisions

Revision 8b1aca5c
Added by Peter Amstutz 12 months ago

Merge branch '17165-vscode-training-doc' refs #17165

Arvados-DCO-1.1-Signed-off-by: Peter Amstutz <>

Revision 046cc7b9 (diff)
Added by Peter Amstutz 12 months ago

Add missing images refs #17165

Arvados-DCO-1.1-Signed-off-by: Peter Amstutz <>

Revision 87df20eb (diff)
Added by Peter Amstutz 10 months ago

Add missing images refs #17165

Arvados-DCO-1.1-Signed-off-by: Peter Amstutz <>

Revision 1919d3b0 (diff)
Added by Peter Amstutz 10 months ago

Put the missing images in the right place refs #17165

Arvados-DCO-1.1-Signed-off-by: Peter Amstutz <>

History

#1 Updated by Peter Amstutz about 1 year ago

  • Status changed from New to In Progress

#2 Updated by Peter Amstutz about 1 year ago

  • Target version changed from 2020-12-16 Sprint to 2021-01-06 Sprint

#3 Updated by Peter Amstutz about 1 year ago

  • Target version changed from 2021-01-06 Sprint to 2021-01-20 Sprint

#4 Updated by Peter Amstutz about 1 year ago

  • Target version changed from 2021-01-20 Sprint to 2021-02-03 Sprint

#5 Updated by Peter Amstutz 12 months ago

  • Target version changed from 2021-02-03 Sprint to 2021-02-17 sprint

#6 Updated by Nico César 12 months ago

review at 984703527b7205372d28a9c27e8356986d3ba278

Is the intention the rake task import_vscode_training from time to time to sync up the content of our repo when https://github.com/arvados/arvados-vscode-cwl-training gets updated? if so, that part looks good to me and I think is ready to merge to Arvados Repo.

about the content of the training, this are my open questions:

there are many references to Windows only install (like /c/Users/MyUsername/.ssh/id_rsa.pub), shall we add a Note that this is Windows only or shall we expand to other operating systems?

Step 1.3.iv (see screenshot) could be confusing if no shell nodes are available.

We should add notes/screenshot of what to expect. Since users can be doing a lot of steps but is something looks fishy should be pointed out.

#7 Updated by Peter Amstutz 12 months ago

Nico César wrote:

review at 984703527b7205372d28a9c27e8356986d3ba278

Is the intention the rake task import_vscode_training from time to time to sync up the content of our repo when https://github.com/arvados/arvados-vscode-cwl-training gets updated? if so, that part looks good to me and I think is ready to merge to Arvados Repo.

about the content of the training, this are my open questions:

there are many references to Windows only install (like /c/Users/MyUsername/.ssh/id_rsa.pub), shall we add a Note that this is Windows only or shall we expand to other operating systems?

I tweaked the text a bit to clarify which instructions are Windows only and which apply to any OS. There's really very little that is Windows specific.

Step 1.3.iv (see screenshot) could be confusing if no shell nodes are available.

I'm assuming that users have access to shell nodes, because otherwise none of the rest of the instructions work as written. If you are on Linux and have the Arvados Python SDK installed most of the instructions could still apply, I'm assuming Linux users are more likely to be able to figure that out on their own.

We should add notes/screenshot of what to expect. Since users can be doing a lot of steps but is something looks fishy should be pointed out.

I did that with some of the VSCode icons, although not with Workbench 2. Screenshots can go stale very quickly when the thing you are documenting changes a lot. I'm also not sure where people are most likely to get stuck and need extra visual help. I'm open to suggestions but I'd like to get to merging as-is so that I can send Roche a link to the page as displayed on our documentation site instead of it being a separate github repo.

#8 Updated by Nico César 12 months ago

Step 2.4 forced me to uninstall and install the extension. See 3 screenshots

#9 Updated by Nico César 12 months ago

in 1.3 there could be a bug related to wb2 and admins (or maybe users too...) See Bug #17357

#10 Updated by Nico César 12 months ago

section 2.6 shouldn't be labled "Go to Arvados Workbench" since there is a back and forth from wb to vscode

I would add:
3.1.iv -> "WORKFLOW_UUID should appear in the directory. You can double check your submission on workbench searching for that UUID"

#11 Updated by Peter Amstutz 12 months ago

Nico César wrote:

Step 2.4 forced me to uninstall and install the extension. See 3 screenshots

Shouldn't be necessary to uninstall. You do need to install it on the remote host, if for some reason you installed it locally, that isn't totally obvious, so I added a note.

Nico César wrote:

in 1.3 there could be a bug related to wb2 and admins (or maybe users too...) See Bug #17357

You're right, that's a bug, but that is out of scope for this story, most people doing this won't be admins.

Nico César wrote:

section 2.6 shouldn't be labled "Go to Arvados Workbench" since there is a back and forth from wb to vscode

Right, that's a little confusing, I adjusted the text and order a bit.

I would add:
3.1.iv -> "WORKFLOW_UUID should appear in the directory. You can double check your submission on workbench searching for that UUID"

I added a note about the file showing up. I didn't get into what the contents of the file means, the user doesn't need to know all the details.

17165-vscode-training-doc @ 5ccc1a94d1621e319990a4362c131d5ab776c478

#12 Updated by Nico César 12 months ago

5ccc1a94d1621e319990a4362c131d5ab776c478

LGTM, we can always improve later (and re-create a arvados repo merge.)

#13 Updated by Peter Amstutz 11 months ago

  • Status changed from In Progress to Resolved

#14 Updated by Peter Amstutz 8 months ago

  • Release set to 38

Also available in: Atom PDF